dd34ba0 · servant · git.iko.soy

git.iko.soy/servant

on master help sign in

Merge remote-tracking branch 'upstream/master' into wip-notes

dd34ba0Christian Marie12 years ago

.gitignore+16−2

compare with master

unifiedsplit

@@ -1,3 +1,17 @@

1−.cabal-sandbox

2−cabal.sandbox.config

3dist

1dist

2+cabal-dev

3+*.o

4+*.hi

5+*.chi

6+*.chs.h

7+*.dyn_o

8+*.dyn_hi

9+.virtualenv

10+.hpc

11+.hsenv

12+.cabal-sandbox/

13+cabal.sandbox.config

14+cabal.config

15+*.prof

16+*.aux

17+*.hp

example/greet.hs+8−1

@@ -37,6 +37,13 @@ instance ToParam (QueryParam "capital" Bool) where

37 \Default is false."

38 Normal

40+instance ToParam (MatrixParam "lang" String) where

41+ toParam _ =

42+ DocQueryParam "lang"

43+ ["en", "sv", "fr"]

44+ "Get the greeting message selected language. Default is en."

45+ Normal

46+

40instance ToSample Greet where

47instance ToSample Greet where

41 toSample = Just $ Greet "Hello, haskeller!"

48 toSample = Just $ Greet "Hello, haskeller!"

@@ -59,7 +66,7 @@ intro2 = DocIntro "This title is below the last"

59-- API specification

66-- API specification

60type TestApi =

67type TestApi =

61 -- GET /hello/:name?capital={true, false} returns a Greet as JSON

68 -- GET /hello/:name?capital={true, false} returns a Greet as JSON

62− "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet

69+ "hello" :> MatrixParam "lang" String :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet

64 -- POST /greet with a Greet as JSON in the request body,

71 -- POST /greet with a Greet as JSON in the request body,

65 -- returns a Greet as JSON

72 -- returns a Greet as JSON

example/greet.md+18−17

@@ -13,9 +13,7 @@ You'll also note that multiple intros are possible.

13#### Request Body:

15``` javascript

16−{

17− "msg": "Hello, haskeller!"

16+"Hello, haskeller!"

18−}

19```

17```

21#### Response:

19#### Response:

@@ -24,30 +22,37 @@ You'll also note that multiple intros are possible.

24 - If you use ?capital=true

22 - If you use ?capital=true

26``` javascript

24``` javascript

27−{

28− "msg": "HELLO, HASKELLER"

25+"HELLO, HASKELLER"

29−}

30```

26```

32 - If you use ?capital=false

28 - If you use ?capital=false

34``` javascript

30``` javascript

35−{

36− "msg": "Hello, haskeller"

31+"Hello, haskeller"

37−}

38```

32```

40−## GET /hello/:name

34+## GET /hello;lang=<value>/:name

42#### Captures:

36#### Captures:

44- *name*: name of the person to greet

38- *name*: name of the person to greet

40+#### Matrix Parameters**:

41+

42+**hello**:

43+

44+ - lang

45+ - **Values**: *en, sv, fr*

46+ - **Description**: Get the greeting message selected language. Default is en.

47+

48+

49+

50+

46#### GET Parameters:

51#### GET Parameters:

48 - capital

53 - capital

49 - **Values**: *true, false*

54 - **Values**: *true, false*

50− - **Description**: Get the greeting message in uppercase (true) or not (false). Default is false.

55+ - **Description**: Get the greeting message in uppercase (true) or not (false).Default is false.

53#### Response:

58#### Response:

@@ -56,17 +61,13 @@ You'll also note that multiple intros are possible.

56 - If you use ?capital=true

61 - If you use ?capital=true

58``` javascript

63``` javascript

59−{

60− "msg": "HELLO, HASKELLER"

64+"HELLO, HASKELLER"

61−}

62```

65```

64 - If you use ?capital=false

67 - If you use ?capital=false

66``` javascript

69``` javascript

67−{

68− "msg": "Hello, haskeller"

70+"Hello, haskeller"

69−}

70```

71```

72## DELETE /greet/:greetid

73## DELETE /greet/:greetid

src/Servant/Docs.hs+79−8

@@ -73,6 +73,13 @@

73-- > \Default is false."

74-- > Normal

75-- >

76+-- > instance ToParam (MatrixParam "lang" String) where

77+-- > toParam _ =

78+-- > DocQueryParam "lang"

79+-- > ["en", "sv", "fr"]

80+-- > "Get the greeting message selected language. Default is en."

81+-- > Normal

82+-- >

76-- > instance ToSample Greet where

83-- > instance ToSample Greet where

77-- > toSample = Just $ Greet "Hello, haskeller!"

84-- > toSample = Just $ Greet "Hello, haskeller!"

78-- >

85-- >

@@ -95,7 +102,7 @@

95-- > -- API specification

102-- > -- API specification

96-- > type TestApi =

103-- > type TestApi =

97-- > -- GET /hello/:name?capital={true, false} returns a Greet as JSON

104-- > -- GET /hello/:name?capital={true, false} returns a Greet as JSON

98−-- > "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet

105+-- > "hello" :> MatrixParam "lang" String :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet

99-- >

106-- >

100-- > -- POST /greet with a Greet as JSON in the request body,

107-- > -- POST /greet with a Greet as JSON in the request body,

101-- > -- returns a Greet as JSON

108-- > -- returns a Greet as JSON

@@ -116,6 +123,7 @@

116-- > -- > docs testAPI

123-- > -- > docs testAPI

117-- > docsGreet :: API

124-- > docsGreet :: API

118-- > docsGreet = docsWithIntros [intro1, intro2] testApi

125-- > docsGreet = docsWithIntros [intro1, intro2] testApi

126+-- >

119-- > main :: IO ()

127-- > main :: IO ()

120-- > main = putStrLn $ markdown docsGreet

128-- > main = putStrLn $ markdown docsGreet

121module Servant.Docs

129module Servant.Docs

@@ -332,12 +340,13 @@ defResponse = Response 200 []

332-- You can tweak an 'Action' (like the default 'defAction') with these lenses

340-- You can tweak an 'Action' (like the default 'defAction') with these lenses

333-- to transform an action and add some information to it.

341-- to transform an action and add some information to it.

334data Action = Action

342data Action = Action

335− { _captures :: [DocCapture] -- type collected + user supplied info

343+ { _captures :: [DocCapture] -- type collected + user supplied info

336− , _headers :: [Text] -- type collected

344+ , _headers :: [Text] -- type collected

337− , _params :: [DocQueryParam] -- type collected + user supplied info

345+ , _params :: [DocQueryParam] -- type collected + user supplied info

338 , _notes :: [DocNote] -- user supplied

346 , _notes :: [DocNote] -- user supplied

347+ , _mxParams :: [(String, [DocQueryParam])] -- type collected + user supplied info

339− , _rqbody :: Maybe ByteString -- user supplied

348+ , _rqbody :: Maybe ByteString -- user supplied

340− , _response :: Response -- user supplied

349+ , _response :: Response -- user supplied

341 } deriving (Eq, Show)

350 } deriving (Eq, Show)

342

351

343-- Default 'Action'. Has no 'captures', no GET 'params', expects

352-- Default 'Action'. Has no 'captures', no GET 'params', expects

@@ -346,15 +355,16 @@ data Action = Action

346-- Tweakable with lenses.

355-- Tweakable with lenses.

347--

356--

348-- > λ> defAction

357-- > λ> defAction

349−-- > Action {_captures = [], _params = [], _rqbody = Nothing, _response = Response {_respStatus = 200, _respBody = Nothing}}

358+-- > Action {_captures = [], _headers = [], _params = [], _mxParams = [], _rqbody = Nothing, _response = Response {_respStatus = 200, _respBody = Nothing}}

350-- > λ> defAction & response.respStatus .~ 201

359-- > λ> defAction & response.respStatus .~ 201

351−-- > Action {_captures = [], _params = [], _rqbody = Nothing, _response = Response {_respStatus = 201, _respBody = Nothing}}

360+-- > Action {_captures = [], _headers = [], _params = [], _mxParams = [], _rqbody = Nothing, _response = Response {_respStatus = 201, _respBody = Nothing}}

352defAction :: Action

361defAction :: Action

353defAction =

362defAction =

354 Action []

363 Action []

355 []

364 []

356 []

365 []

357 []

366 []

367+ []

358 Nothing

368 Nothing

359 defResponse

369 defResponse

360

370

@@ -473,6 +483,7 @@ markdown api = unlines $

473 "" :

483 "" :

474 notesStr (action ^. notes) ++

484 notesStr (action ^. notes) ++

475 capturesStr (action ^. captures) ++

485 capturesStr (action ^. captures) ++

486+ mxParamsStr (action ^. mxParams) ++

476 headersStr (action ^. headers) ++

487 headersStr (action ^. headers) ++

477 paramsStr (action ^. params) ++

488 paramsStr (action ^. params) ++

478 rqbodyStr (action ^. rqbody) ++

489 rqbodyStr (action ^. rqbody) ++

@@ -515,6 +526,22 @@ markdown api = unlines $

515 captureStr cap =

526 captureStr cap =

516 "- *" ++ (cap ^. capSymbol) ++ "*: " ++ (cap ^. capDesc)

527 "- *" ++ (cap ^. capSymbol) ++ "*: " ++ (cap ^. capDesc)

517

528

529+ mxParamsStr :: [(String, [DocQueryParam])] -> [String]

530+ mxParamsStr [] = []

531+ mxParamsStr l =

532+ "#### Matrix Parameters:" :

533+ "" :

534+ map segmentStr l ++

535+ "" :

536+ []

537+ segmentStr :: (String, [DocQueryParam]) -> String

538+ segmentStr (segment, l) = unlines $

539+ ("**" ++ segment ++ "**:") :

540+ "" :

541+ map paramStr l ++

542+ "" :

543+ []

544+

518 headersStr :: [Text] -> [String]

545 headersStr :: [Text] -> [String]

519 headersStr [] = []

546 headersStr [] = []

520 headersStr l = [""] ++ map headerStr l ++ [""]

547 headersStr l = [""] ++ map headerStr l ++ [""]

@@ -685,6 +712,50 @@ instance (KnownSymbol sym, ToParam (QueryFlag sym), HasDocs sublayout)

685 paramP = Proxy :: Proxy (QueryFlag sym)

712 paramP = Proxy :: Proxy (QueryFlag sym)

686 action' = over params (|> toParam paramP) action

713 action' = over params (|> toParam paramP) action

687

714

715+

716+instance (KnownSymbol sym, ToParam (MatrixParam sym a), HasDocs sublayout)

717+ => HasDocs (MatrixParam sym a :> sublayout) where

718+

719+ docsFor Proxy (endpoint, action) =

720+ docsFor sublayoutP (endpoint', action')

721+

722+ where sublayoutP = Proxy :: Proxy sublayout

723+ paramP = Proxy :: Proxy (MatrixParam sym a)

724+ segment = endpoint ^. (path._last)

725+ segment' = action ^. (mxParams._last._1)

726+ endpoint' = over (path._last) (\p -> p ++ ";" ++ symbolVal symP ++ "=<value>") endpoint

727+

728+ action' = if segment' /= segment

729+ -- This is the first matrix parameter for this segment, insert a new entry into the mxParams list

730+ then over mxParams (|> (segment, [toParam paramP])) action

731+ -- We've already inserted a matrix parameter for this segment, append to the existing list

732+ else action & mxParams._last._2 <>~ [toParam paramP]

733+ symP = Proxy :: Proxy sym

734+

735+

736+instance (KnownSymbol sym, {- ToParam (MatrixParams sym a), -} HasDocs sublayout)

737+ => HasDocs (MatrixParams sym a :> sublayout) where

738+

739+ docsFor Proxy (endpoint, action) =

740+ docsFor sublayoutP (endpoint', action)

741+

742+ where sublayoutP = Proxy :: Proxy sublayout

743+ endpoint' = over path (\p -> p ++ [";" ++ symbolVal symP ++ "=<value>"]) endpoint

744+ symP = Proxy :: Proxy sym

745+

746+

747+instance (KnownSymbol sym, {- ToParam (MatrixFlag sym), -} HasDocs sublayout)

748+ => HasDocs (MatrixFlag sym :> sublayout) where

749+

750+ docsFor Proxy (endpoint, action) =

751+ docsFor sublayoutP (endpoint', action)

752+

753+ where sublayoutP = Proxy :: Proxy sublayout

754+

755+ endpoint' = over path (\p -> p ++ [";" ++ symbolVal symP]) endpoint

756+ symP = Proxy :: Proxy sym

757+

758+

688instance HasDocs Raw where

759instance HasDocs Raw where

689 docsFor _proxy (endpoint, action) =

760 docsFor _proxy (endpoint, action) =

690 single endpoint action

761 single endpoint action