git.iko.soy/typeable/servant
on master help sign in
add doc generation support for QueryParams and QueryFlag
commitdf12f9b9bd3f79b130a4192be433c105f72dae02 authorAlp Mestanogullari <alpmestan@gmail.com> dateThu 30 Oct 2014, 12:15 (12 years ago) parente774af7
3 files changed+37−2
compare with master
unifiedsplit
example/greet.hs+1 src/Servant/API/QueryParam.hs+20 src/Servant/Docs.hs+16−2
example/greet.hs+1
@@ -43,6 +43,7 @@ instance ToParam (QueryParam "capital" Bool) where
4343 DocQueryParam "capital"
4444 ["true", "false"]
4545 "Get the greeting message in uppercase (true) or not (false). Default is false."
46+ Normal
4647
4748instance ToSample Greet where
4849 toSample Proxy = Just (encode g)
src/Servant/API/QueryParam.hs+20
@@ -110,6 +110,16 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)
110110 pname' = symbolVal (Proxy :: Proxy sym)
111111 paramlist' = map (Just . toText) paramlist
112112
113+instance (KnownSymbol sym, ToParam (QueryParams sym a), HasDocs sublayout)
114+ => HasDocs (QueryParams sym a :> sublayout) where
115+
116+ docsFor Proxy (endpoint, action) =
117+ docsFor sublayoutP (endpoint, action')
118+
119+ where sublayoutP = Proxy :: Proxy sublayout
120+ paramP = Proxy :: Proxy (QueryParams sym a)
121+ action' = over params (|> toParam paramP) action
122+
113123-- | Retrieve a value-less boolean from the query string.
114124data QueryFlag a
115125
@@ -142,3 +152,13 @@ instance (KnownSymbol sym, HasClient sublayout)
142152 else req
143153
144154 where paramname = cs $ symbolVal (Proxy :: Proxy sym)
155+
156+instance (KnownSymbol sym, ToParam (QueryFlag sym), HasDocs sublayout)
157+ => HasDocs (QueryFlag sym :> sublayout) where
158+
159+ docsFor Proxy (endpoint, action) =
160+ docsFor sublayoutP (endpoint, action')
161+
162+ where sublayoutP = Proxy :: Proxy sublayout
163+ paramP = Proxy :: Proxy (QueryFlag sym)
164+ action' = over params (|> toParam paramP) action
src/Servant/Docs.hs+16−2
@@ -95,7 +95,7 @@ module Servant.Docs
9595 , Endpoint, path, method, defEndpoint
9696 , API, emptyAPI
9797 , DocCapture(..), capSymbol, capDesc
98− , DocQueryParam(..), paramName, paramValues, paramDesc
98+ , DocQueryParam(..), ParamKind(..), paramName, paramValues, paramDesc, paramKind
9999 , Response, respStatus, respBody, defResponse
100100 , Action, captures, params, rqbody, response, defAction
101101 , single
@@ -199,8 +199,17 @@ data DocQueryParam = DocQueryParam
199199 { _paramName :: String -- type supplied
200200 , _paramValues :: [String] -- user supplied
201201 , _paramDesc :: String -- user supplied
202+ , _paramKind :: ParamKind
202203 } deriving (Eq, Show)
203204
205+-- | Type of GET parameter:
206+--
207+-- - Normal corresponds to @QueryParam@, i.e your usual GET parameter
208+-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values
209+-- - Flag corresponds to @QueryFlag@, i.e a value-less GET parameter
210+data ParamKind = Normal | List | Flag
211+ deriving (Eq, Show)
212+
204213-- | A type to represent an HTTP response. Has an 'Int' status and
205214-- a 'Maybe ByteString' response body. Tweak 'defResponse' using
206215-- the 'respStatus' and 'respBody' lenses if you want.
@@ -373,9 +382,14 @@ printMarkdown = imapM_ printEndpoint
373382 putStrLn ""
374383 paramStr param = do
375384 putStrLn $ " - " ++ param ^. paramName
376− when (not $ null values) $
385+ when (not (null values) || param ^. paramKind /= Flag) $
377386 putStrLn $ " - **Values**: *" ++ intercalate ", " values ++ "*"
378387 putStrLn $ " - **Description**: " ++ param ^. paramDesc
388+ when (param ^. paramKind == List) $
389+ putStrLn $ " - This parameter is a **list**. All GET parameters with the name "
390+ ++ param ^. paramName ++ "[] will forward their values in a list to the handler."
391+ when (param ^. paramKind == Flag) $
392+ putStrLn $ " - This parameter is a **flag**. This means no value is expected to be associated to this parameter."
379393
380394 where values = param ^. paramValues
381395