df12f9b · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

add doc generation support for QueryParams and QueryFlag

df12f9bAlp Mestanogullari12 years ago

example/greet.hs+1

compare with master

unifiedsplit

@@ -43,6 +43,7 @@ instance ToParam (QueryParam "capital" Bool) where

43 DocQueryParam "capital"

44 ["true", "false"]

45 "Get the greeting message in uppercase (true) or not (false). Default is false."

46+ Normal

47instance ToSample Greet where

48instance ToSample Greet where

48 toSample Proxy = Just (encode g)

49 toSample Proxy = Just (encode g)

src/Servant/API/QueryParam.hs+20

@@ -110,6 +110,16 @@ instance (KnownSymbol sym, ToText a, HasClient sublayout)

110 pname' = symbolVal (Proxy :: Proxy sym)

111 paramlist' = map (Just . toText) paramlist

112

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+

113-- | Retrieve a value-less boolean from the query string.

123-- | Retrieve a value-less boolean from the query string.

114data QueryFlag a

124data QueryFlag a

115

125

@@ -142,3 +152,13 @@ instance (KnownSymbol sym, HasClient sublayout)

142 else req

152 else req

143

153

144 where paramname = cs $ symbolVal (Proxy :: Proxy sym)

154 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

95 , Endpoint, path, method, defEndpoint

96 , API, emptyAPI

97 , DocCapture(..), capSymbol, capDesc

98− , DocQueryParam(..), paramName, paramValues, paramDesc

98+ , DocQueryParam(..), ParamKind(..), paramName, paramValues, paramDesc, paramKind

99 , Response, respStatus, respBody, defResponse

100 , Action, captures, params, rqbody, response, defAction

101 , single

@@ -199,8 +199,17 @@ data DocQueryParam = DocQueryParam

199 { _paramName :: String -- type supplied

200 , _paramValues :: [String] -- user supplied

201 , _paramDesc :: String -- user supplied

202+ , _paramKind :: ParamKind

202 } deriving (Eq, Show)

203 } deriving (Eq, Show)

203

204

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+

204-- | A type to represent an HTTP response. Has an 'Int' status and

213-- | A type to represent an HTTP response. Has an 'Int' status and

205-- a 'Maybe ByteString' response body. Tweak 'defResponse' using

214-- a 'Maybe ByteString' response body. Tweak 'defResponse' using

206-- the 'respStatus' and 'respBody' lenses if you want.

215-- the 'respStatus' and 'respBody' lenses if you want.

@@ -373,9 +382,14 @@ printMarkdown = imapM_ printEndpoint

373 putStrLn ""

382 putStrLn ""

374 paramStr param = do

383 paramStr param = do

375 putStrLn $ " - " ++ param ^. paramName

384 putStrLn $ " - " ++ param ^. paramName

376− when (not $ null values) $

385+ when (not (null values) || param ^. paramKind /= Flag) $

377 putStrLn $ " - **Values**: *" ++ intercalate ", " values ++ "*"

386 putStrLn $ " - **Values**: *" ++ intercalate ", " values ++ "*"

378 putStrLn $ " - **Description**: " ++ param ^. paramDesc

387 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."

379

393

380 where values = param ^. paramValues

394 where values = param ^. paramValues

381

395