git.iko.soy/servant
on master help sign in
Fix servant-docs code sample in README (#1335)
e3a29adSzabo Gergely
servant-docs/README.md+44−11
compare with master
unifiedsplit
@@ -2,24 +2,56 @@
2
2
3![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
3![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
4
4
5−Generate API docs for your *servant* webservice. Feel free to also take a look at [servant-pandoc](https://github.com/mpickering/servant-pandoc) which uses this package to target a broad range of output formats using the excellent **pandoc**.
5+Generate API docs for your _servant_ webservice. Feel free to also take a look at [servant-pandoc](https://github.com/mpickering/servant-pandoc) which uses this package to target a broad range of output formats using the excellent **pandoc**.
6
6
7## Example
7## Example
8
8
9See [here](https://github.com/haskell-servant/servant/blob/master/servant-docs/example/greet.md) for the output of the following program.
9See [here](https://github.com/haskell-servant/servant/blob/master/servant-docs/example/greet.md) for the output of the following program.
10
10
11−``` haskell
11+```haskell
12{-# LANGUAGE DataKinds #-}
12{-# LANGUAGE DataKinds #-}
13−{-# LANGUAGE PolyKinds #-}
14−{-# LANGUAGE TypeFamilies #-}
15{-# LANGUAGE DeriveGeneric #-}
13{-# LANGUAGE DeriveGeneric #-}
16−{-# LANGUAGE TypeOperators #-}
17{-# LANGUAGE FlexibleInstances #-}
14{-# LANGUAGE FlexibleInstances #-}
15+{-# LANGUAGE MultiParamTypeClasses #-}
18{-# LANGUAGE OverloadedStrings #-}
16{-# LANGUAGE OverloadedStrings #-}
17+{-# LANGUAGE PolyKinds #-}
18+{-# LANGUAGE TypeFamilies #-}
19+{-# LANGUAGE TypeOperators #-}
19
20
20−import Data.Proxy
21+import Data.Aeson (FromJSON, ToJSON)
22+import Data.Proxy (Proxy (..))
23+import Data.String.Conversions (cs)
21−import Data.Text
24+import Data.Text (Text)
25+import GHC.Generics (Generic)
26+import Servant.API
27+ ( (:<|>),
28+ (:>),
29+ Capture,
30+ Delete,
31+ Get,
32+ JSON,
33+ MimeRender,
34+ PlainText,
35+ Post,
36+ QueryParam,
37+ ReqBody,
38+ mimeRender,
39+ )
22import Servant.Docs
40import Servant.Docs
41+ ( API,
42+ DocCapture (..),
43+ DocQueryParam (..),
44+ ParamKind (..),
45+ ToCapture,
46+ ToParam,
47+ ToSample,
48+ docs,
49+ markdown,
50+ singleSample,
51+ toCapture,
52+ toParam,
53+ toSamples,
54+ )
23
55
24-- our type for a Greeting message
56-- our type for a Greeting message
25data Greet = Greet { _msg :: Text }
57data Greet = Greet { _msg :: Text }
@@ -29,6 +61,7 @@ data Greet = Greet { _msg :: Text }
29-- 'MimeRender' instance for 'JSON'.
61-- 'MimeRender' instance for 'JSON'.
30instance FromJSON Greet
62instance FromJSON Greet
31instance ToJSON Greet
63instance ToJSON Greet
64+instance ToSample ()
32
65
33-- We can also implement 'MimeRender' explicitly for additional formats.
66-- We can also implement 'MimeRender' explicitly for additional formats.
34instance MimeRender PlainText Greet where
67instance MimeRender PlainText Greet where
@@ -36,8 +69,7 @@ instance MimeRender PlainText Greet where
36
69
37-- we provide a sample value for the 'Greet' type
70-- we provide a sample value for the 'Greet' type
38instance ToSample Greet where
71instance ToSample Greet where
39− toSample = Just g
72+ toSamples _ = singleSample g
40−
41 where g = Greet "Hello, haskeller!"
73 where g = Greet "Hello, haskeller!"
42
74
43instance ToParam (QueryParam "capital" Bool) where
75instance ToParam (QueryParam "capital" Bool) where
@@ -45,6 +77,7 @@ instance ToParam (QueryParam "capital" Bool) where
45 DocQueryParam "capital"
77 DocQueryParam "capital"
46 ["true", "false"]
78 ["true", "false"]
47 "Get the greeting message in uppercase (true) or not (false). Default is false."
79 "Get the greeting message in uppercase (true) or not (false). Default is false."
80+ Normal
48
81
49instance ToCapture (Capture "name" Text) where
82instance ToCapture (Capture "name" Text) where
50 toCapture _ = DocCapture "name" "name of the person to greet"
83 toCapture _ = DocCapture "name" "name of the person to greet"
@@ -55,8 +88,8 @@ instance ToCapture (Capture "greetid" Text) where
55-- API specification
88-- API specification
56type TestApi =
89type TestApi =
57 "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
90 "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
58− :<|> "greet" :> RQBody '[JSON] Greet :> Post '[JSON] Greet
91+ :<|> "greet" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet
59− :<|> "delete" :> Capture "greetid" Text :> Delete '[] ()
92+ :<|> "delete" :> Capture "greetid" Text :> Delete '[JSON] ()
60
93
61testApi :: Proxy TestApi
94testApi :: Proxy TestApi
62testApi = Proxy
95testApi = Proxy