eeva/servant
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #790 from ivan-m/query-param-method

Browse source 
Document the type of endpoint a parameter belongs to
This commit is contained in:
Oleg Grenrus 2017-07-31 11:41:13 +03:00 committed by GitHub
commit 24035ddd85
1 changed files with 21 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
servant-docs/src/Servant/Docs/Internal.hs
View file

@ -125,9 +125,10 @@ data DocCapture = DocCapture
, _capDesc :: String -- user supplied , _capDesc :: String -- user supplied
} deriving (Eq, Ord, Show) } deriving (Eq, Ord, Show)
-- | A type to represent a /GET/ parameter from the Query String. Holds its name, -- | A type to represent a /GET/ (or other possible 'HTTP.Method')
-- the possible values (leave empty if there isn't a finite number of them), -- parameter from the Query String. Holds its name, the possible
-- and a description of how it influences the output or behavior. -- values (leave empty if there isn't a finite number of them), and
-- a description of how it influences the output or behavior.
-- --
-- Write a 'ToParam' instance for your GET parameter types -- Write a 'ToParam' instance for your GET parameter types
data DocQueryParam = DocQueryParam data DocQueryParam = DocQueryParam
@ -185,7 +186,7 @@ defaultDocOptions :: DocOptions
defaultDocOptions = DocOptions defaultDocOptions = DocOptions
{ _maxSamples = 5 } { _maxSamples = 5 }
-- | Type of GET parameter: -- | Type of GET (or other 'HTTP.Method') parameter:
-- --
-- - Normal corresponds to @QueryParam@, i.e your usual GET parameter -- - Normal corresponds to @QueryParam@, i.e your usual GET parameter
-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values -- - List corresponds to @QueryParams@, i.e GET parameters with multiple values
@ -235,7 +236,7 @@ defResponse = Response
-- at an endpoint, with its lenses: -- at an endpoint, with its lenses:
-- --
-- - List of captures ('captures') -- - List of captures ('captures')
-- - List of GET parameters ('params') -- - List of GET (or other 'HTTP.Method') parameters ('params')
-- - What the request body should look like, if any is requested ('rqbody') -- - What the request body should look like, if any is requested ('rqbody')
-- - What the response should be if everything goes well ('response') -- - What the response should be if everything goes well ('response')
-- --
@ -263,8 +264,8 @@ combineAction :: Action -> Action -> Action
Action a c h p n m ts body resp `combineAction` Action a' c' h' p' n' m' _ _ _ = Action a c h p n m ts body resp `combineAction` Action a' c' h' p' n' m' _ _ _ =
Action (a <> a') (c <> c') (h <> h') (p <> p') (n <> n') (m <> m') ts body resp Action (a <> a') (c <> c') (h <> h') (p <> p') (n <> n') (m <> m') ts body resp
-- | Default 'Action'. Has no 'captures', no GET 'params', expects no -- | Default 'Action'. Has no 'captures', no query 'params', expects
-- request body ('rqbody') and the typical response is 'defResponse'. -- no request body ('rqbody') and the typical response is 'defResponse'.
-- --
-- Tweakable with lenses. -- Tweakable with lenses.
-- --
@ -487,8 +488,8 @@ sampleByteStrings ctypes@Proxy Proxy =
enc (t, s) = uncurry (t,,) <$> allMimeRender ctypes s enc (t, s) = uncurry (t,,) <$> allMimeRender ctypes s
in concatMap enc samples' in concatMap enc samples'
-- | The class that helps us automatically get documentation -- | The class that helps us automatically get documentation for GET
-- for GET parameters. -- (or other 'HTTP.Method') parameters.
-- --
-- Example of an instance: -- Example of an instance:
-- --
@ -529,14 +530,16 @@ markdown api = unlines $
authStr (action ^. authInfo) ++ authStr (action ^. authInfo) ++
capturesStr (action ^. captures) ++ capturesStr (action ^. captures) ++
headersStr (action ^. headers) ++ headersStr (action ^. headers) ++
paramsStr (action ^. params) ++ paramsStr meth (action ^. params) ++
rqbodyStr (action ^. rqtypes) (action ^. rqbody) ++ rqbodyStr (action ^. rqtypes) (action ^. rqbody) ++
responseStr (action ^. response) ++ responseStr (action ^. response) ++
[] []
where str = "## " ++ BSC.unpack (endpoint^.method) where str = "## " ++ BSC.unpack meth
++ " " ++ showPath (endpoint^.path) ++ " " ++ showPath (endpoint^.path)
meth = endpoint ^. method
introsStr :: [DocIntro] -> [String] introsStr :: [DocIntro] -> [String]
introsStr = concatMap introStr introsStr = concatMap introStr
@ -598,23 +601,23 @@ markdown api = unlines $
where headerStr hname = "- This endpoint is sensitive to the value of the **" where headerStr hname = "- This endpoint is sensitive to the value of the **"
++ unpack hname ++ "** HTTP header." ++ unpack hname ++ "** HTTP header."
paramsStr :: [DocQueryParam] -> [String] paramsStr :: HTTP.Method -> [DocQueryParam] -> [String]
paramsStr [] = [] paramsStr _ [] = []
paramsStr l = paramsStr m l =
"#### GET Parameters:" : ("#### " ++ cs m ++ " Parameters:") :
"" : "" :
map paramStr l ++ map (paramStr m) l ++
"" : "" :
[] []
paramStr param = unlines $ paramStr m param = unlines $
("- " ++ param ^. paramName) : ("- " ++ param ^. paramName) :
(if (not (null values) || param ^. paramKind /= Flag) (if (not (null values) || param ^. paramKind /= Flag)
then [" - **Values**: *" ++ intercalate ", " values ++ "*"] then [" - **Values**: *" ++ intercalate ", " values ++ "*"]
else []) ++ else []) ++
(" - **Description**: " ++ param ^. paramDesc) : (" - **Description**: " ++ param ^. paramDesc) :
(if (param ^. paramKind == List) (if (param ^. paramKind == List)
then [" - This parameter is a **list**. All GET parameters with the name " then [" - This parameter is a **list**. All " ++ cs m ++ " parameters with the name "
++ param ^. paramName ++ "[] will forward their values in a list to the handler."] ++ param ^. paramName ++ "[] will forward their values in a list to the handler."]
else []) ++ else []) ++
(if (param ^. paramKind == Flag) (if (param ^. paramKind == Flag)