0edde41 · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

first shot (doesn't build though) at multiple responses in the docs

0edde41Alp Mestanogullari12 years ago

src/Servant/Docs.hs+39−19

compare with master

unifiedsplit

@@ -1,10 +1,12 @@

1{-# LANGUAGE TypeFamilies #-}

2{-# LANGUAGE DeriveGeneric #-}

3+{-# LANGUAGE TupleSections #-}

3{-# LANGUAGE TypeOperators #-}

4{-# LANGUAGE TypeOperators #-}

5+{-# LANGUAGE TemplateHaskell #-}

4{-# LANGUAGE FlexibleContexts #-}

6{-# LANGUAGE FlexibleContexts #-}

5{-# LANGUAGE FlexibleInstances #-}

7{-# LANGUAGE FlexibleInstances #-}

8+{-# LANGUAGE OverloadedStrings #-}

6{-# LANGUAGE ScopedTypeVariables #-}

9{-# LANGUAGE ScopedTypeVariables #-}

7−{-# LANGUAGE TemplateHaskell #-}

9-------------------------------------------------------------------------------

11-------------------------------------------------------------------------------

10-- | This module lets you get API docs for free. It lets generate

12-- | This module lets you get API docs for free. It lets generate

@@ -83,12 +85,10 @@ module Servant.Docs

83 ( -- * 'HasDocs' class and key functions

85 ( -- * 'HasDocs' class and key functions

84 HasDocs(..), docs, markdown

86 HasDocs(..), docs, markdown

86− {- , -- * Serving the documentation

87− serveDocumentation -}

88−

89 , -- * Classes you need to implement for your types

88 , -- * Classes you need to implement for your types

90 ToSample(..)

89 ToSample(..)

91 , sampleByteString

90 , sampleByteString

91+ , sampleByteStrings

92 , ToParam(..)

93 , ToCapture(..)

@@ -114,6 +114,7 @@ import Data.ByteString.Lazy.Char8 (ByteString)

114import Data.Hashable

115import Data.HashMap.Strict (HashMap)

116import Data.List

117+import Data.Maybe (listToMaybe)

117import Data.Monoid

118import Data.Monoid

118import Data.Proxy

119import Data.Proxy

119import Data.Text (Text, pack, unpack)

120import Data.Text (Text, pack, unpack)

@@ -123,6 +124,7 @@ import GHC.TypeLits

123import Servant.API

124import Servant.API

124

125

125import qualified Data.HashMap.Strict as HM

126import qualified Data.HashMap.Strict as HM

127+import qualified Data.Text as T

126

128

127-- | Supported HTTP request methods

129-- | Supported HTTP request methods

128data Method = DocDELETE -- ^ the DELETE method

130data Method = DocDELETE -- ^ the DELETE method

@@ -233,12 +235,12 @@ data ParamKind = Normal | List | Flag

233-- Can be tweaked with two lenses.

235-- Can be tweaked with two lenses.

234--

236--

235-- > λ> defResponse

237-- > λ> defResponse

236−-- > Response {_respStatus = 200, _respBody = Nothing}

238+-- > Response {_respStatus = 200, _respBody = []}

237−-- > λ> defResponse & respStatus .~ 204 & respBody .~ Just "[]"

239+-- > λ> defResponse & respStatus .~ 204 & respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]

238−-- > Response {_respStatus = 204, _respBody = Just "[]"}

240+-- > Response {_respStatus = 204, _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}

239data Response = Response

241data Response = Response

240 { _respStatus :: Int

242 { _respStatus :: Int

241− , _respBody :: Maybe ByteString

243+ , _respBody :: [(Text, ByteString)]

242 } deriving (Eq, Show)

244 } deriving (Eq, Show)

243

245

244-- | Default response: status code 200, no response body.

246-- | Default response: status code 200, no response body.

@@ -250,7 +252,7 @@ data Response = Response

250-- > λ> defResponse & respStatus .~ 204 & respBody .~ Just "[]"

252-- > λ> defResponse & respStatus .~ 204 & respBody .~ Just "[]"

251-- > Response {_respStatus = 204, _respBody = Just "[]"}

253-- > Response {_respStatus = 204, _respBody = Just "[]"}

252defResponse :: Response

254defResponse :: Response

253−defResponse = Response 200 Nothing

255+defResponse = Response 200 []

254

256

255-- | A datatype that represents everything that can happen

257-- | A datatype that represents everything that can happen

256-- at an endpoint, with its lenses:

258-- at an endpoint, with its lenses:

@@ -334,15 +336,29 @@ class HasDocs layout where

334-- > toSample = Just g

336-- > toSample = Just g

335-- >

337-- >

336-- > where g = Greet "Hello, haskeller!"

338-- > where g = Greet "Hello, haskeller!"

339+--

340+-- You can also instantiate this class using 'toSamples' instead of

341+-- 'toSample': it lets you specify different responses along with

342+-- some context (as 'Text') that explains when you're supposed to

343+-- get the corresponding response.

337class ToJSON a => ToSample a where

344class ToJSON a => ToSample a where

345+ {-# MINIMAL (toSample | toSamples) #-}

338 toSample :: Maybe a

346 toSample :: Maybe a

347+ toSample = fmap snd $ listToMaybe samples

348+ where samples = toSamples :: [(Text, a)]

339

349

340−instance ToSample () where

350+ toSamples :: [(Text, a)]

351+ toSamples = maybe [] (return . ("",)) s

341− toSample = Just ()

352+ where s = toSample :: Maybe a

342

353

343−sampleByteString :: forall a . ToSample a => Proxy a -> Maybe ByteString

354+sampleByteString :: ToSample a => Proxy a -> Maybe ByteString

344sampleByteString Proxy = fmap encodePretty (toSample :: Maybe a)

355sampleByteString Proxy = fmap encodePretty (toSample :: Maybe a)

345

356

357+sampleByteStrings :: ToSample a => Proxy a -> [(Text, ByteString)]

358+sampleByteStrings Proxy = samples & traverse._2 %~ encodePretty

359+

360+ where samples = toSamples :: [(Text, a)]

361+

346-- | The class that helps us automatically get documentation

362-- | The class that helps us automatically get documentation

347-- for GET parameters.

363-- for GET parameters.

348--

364--

@@ -448,9 +464,13 @@ markdown = unlines . concat . map (uncurry printEndpoint) . HM.toList

448 "**Response**: " :

464 "**Response**: " :

449 "" :

465 "" :

450 (" - Status code " ++ show (resp ^. respStatus)) :

466 (" - Status code " ++ show (resp ^. respStatus)) :

467+ bodies

468+

451− (resp ^. respBody &

469+ where bodies = case resp ^. respBody of

452− maybe [" - No response body\n"]

470+ [] -> [" - No response body\n"]

453− (\b -> " - Response body as below." : jsonStr b))

471+ [("", r)] -> " - Response body as below." : jsonStr r

472+ xs ->

473+ concatMap (\(ctx, r) -> (" - " <> T.unpack ctx) : jsonStr r) xs

454

474

455-- * Instances

475-- * Instances

456

476

@@ -489,7 +509,7 @@ instance HasDocs Delete where

489

509

490 where endpoint' = endpoint & method .~ DocDELETE

510 where endpoint' = endpoint & method .~ DocDELETE

491

511

492− action' = action & response.respBody .~ Nothing

512+ action' = action & response.respBody .~ []

493 & response.respStatus .~ 204

513 & response.respStatus .~ 204

494

514

495instance ToSample a => HasDocs (Get a) where

515instance ToSample a => HasDocs (Get a) where

@@ -497,7 +517,7 @@ instance ToSample a => HasDocs (Get a) where

497 single endpoint' action'

517 single endpoint' action'

498

518

499 where endpoint' = endpoint & method .~ DocGET

519 where endpoint' = endpoint & method .~ DocGET

500− action' = action & response.respBody .~ sampleByteString p

520+ action' = action & response.respBody .~ sampleByteStrings p

501 p = Proxy :: Proxy a

521 p = Proxy :: Proxy a

502

522

503instance (KnownSymbol sym, HasDocs sublayout)

523instance (KnownSymbol sym, HasDocs sublayout)

@@ -515,7 +535,7 @@ instance ToSample a => HasDocs (Post a) where

515

535

516 where endpoint' = endpoint & method .~ DocPOST

536 where endpoint' = endpoint & method .~ DocPOST

517

537

518− action' = action & response.respBody .~ sampleByteString p

538+ action' = action & response.respBody .~ sampleByteStrings p

519 & response.respStatus .~ 201

539 & response.respStatus .~ 201

520

540

521 p = Proxy :: Proxy a

541 p = Proxy :: Proxy a

@@ -526,7 +546,7 @@ instance ToSample a => HasDocs (Put a) where

526

546

527 where endpoint' = endpoint & method .~ DocPUT

547 where endpoint' = endpoint & method .~ DocPUT

528

548

529− action' = action & response.respBody .~ sampleByteString p

549+ action' = action & response.respBody .~ sampleByteStrings p

530 & response.respStatus .~ 200

550 & response.respStatus .~ 200

531

551

532 p = Proxy :: Proxy a

552 p = Proxy :: Proxy a