git.iko.soy/servant
on master help sign in
polish up cabal file, add README and output of the example
commit22615210024a354d1a5e4308bb1a1a507dd7f861 authorAlp Mestanogullari <alpmestan@gmail.com> dateMon 8 Dec 2014, 11:25 (12 years ago) parentd517bfa
3 files changed+185−4
compare with master
unifiedsplit
README.md+67 example/greet.md+52 servant-docs.cabal+66−4
README.mdnew file+67
@@ -0,0 +1,67 @@
1+# servant-docs
2+
3+[![Build Status](https://secure.travis-ci.org/haskell-servant/servant-docs.svg)](http://travis-ci.org/haskell-servant/servant-docs)
4+
5+![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
6+
7+Generate API docs for your *servant* webservice.
8+
9+## Example
10+
11+See [here](https://github.com/haskell-servant/servant-docs/blob/master/example/greet.md) for the output of the following program.
12+
13+``` haskell
14+{-# LANGUAGE DataKinds #-}
15+{-# LANGUAGE PolyKinds #-}
16+{-# LANGUAGE TypeFamilies #-}
17+{-# LANGUAGE DeriveGeneric #-}
18+{-# LANGUAGE TypeOperators #-}
19+{-# LANGUAGE FlexibleInstances #-}
20+{-# LANGUAGE OverloadedStrings #-}
21+
22+import Data.Proxy
23+import Data.Text
24+import Servant
25+
26+-- our type for a Greeting message
27+data Greet = Greet { _msg :: Text }
28+ deriving (Generic, Show)
29+
30+-- we get our JSON serialization for free
31+instance FromJSON Greet
32+instance ToJSON Greet
33+
34+-- we provide a sample value for the 'Greet' type
35+instance ToSample Greet where
36+ toSample = Just g
37+
38+ where g = Greet "Hello, haskeller!"
39+
40+instance ToParam (QueryParam "capital" Bool) where
41+ toParam _ =
42+ DocQueryParam "capital"
43+ ["true", "false"]
44+ "Get the greeting message in uppercase (true) or not (false). Default is false."
45+
46+instance ToCapture (Capture "name" Text) where
47+ toCapture _ = DocCapture "name" "name of the person to greet"
48+
49+instance ToCapture (Capture "greetid" Text) where
50+ toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
51+
52+-- API specification
53+type TestApi =
54+ "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet
55+ :<|> "greet" :> RQBody Greet :> Post Greet
56+ :<|> "delete" :> Capture "greetid" Text :> Delete
57+
58+testApi :: Proxy TestApi
59+testApi = Proxy
60+
61+-- Generate the Documentation's ADT
62+greetDocs :: API
63+greetDocs = docs testApi
64+
65+main :: IO ()
66+main = putStrLn $ markdown greetDocs
67+```
example/greet.mdnew file+52
@@ -0,0 +1,52 @@
1+POST /greet
2+-----------
3+
4+**Request Body**:
5+
6+``` javascript
7+{"msg":"Hello, haskeller!"}
8+```
9+
10+**Response**:
11+
12+ - Status code 201
13+ - Response body as below.
14+
15+``` javascript
16+{"msg":"Hello, haskeller!"}
17+```
18+
19+GET /hello/:name
20+----------------
21+
22+**Captures**:
23+
24+- *name*: name of the person to greet
25+
26+**GET Parameters**:
27+
28+ - capital
29+ - **Values**: *true, false*
30+ - **Description**: Get the greeting message in uppercase (true) or not (false). Default is false.
31+
32+
33+**Response**:
34+
35+ - Status code 200
36+ - Response body as below.
37+
38+``` javascript
39+{"msg":"Hello, haskeller!"}
40+```
41+
42+DELETE /greet/:greetid
43+----------------------
44+
45+**Captures**:
46+
47+- *greetid*: identifier of the greet msg to remove
48+
49+**Response**:
50+
51+ - Status code 204
52+ - No response body
servant-docs.cabal+66−4
@@ -1,7 +1,64 @@
11name: servant-docs
22version: 0.2
3−-- synopsis:
4−-- description:
3+synopsis: generate API docs for your servant webservice
4+description:
5+ Library for generating API docs from a servant API definition.
6+ .
7+ Runnable example below that prints API docs in markdown.
8+ .
9+ > {-# LANGUAGE DataKinds #-}
10+ > {-# LANGUAGE PolyKinds #-}
11+ > {-# LANGUAGE TypeFamilies #-}
12+ > {-# LANGUAGE DeriveGeneric #-}
13+ > {-# LANGUAGE TypeOperators #-}
14+ > {-# LANGUAGE FlexibleInstances #-}
15+ > {-# LANGUAGE OverloadedStrings #-}
16+ >
17+ > import Data.Proxy
18+ > import Data.Text
19+ > import Servant
20+ >
21+ > -- our type for a Greeting message
22+ > data Greet = Greet { _msg :: Text }
23+ > deriving (Generic, Show)
24+ >
25+ > -- we get our JSON serialization for free
26+ > instance FromJSON Greet
27+ > instance ToJSON Greet
28+ >
29+ > -- we provide a sample value for the 'Greet' type
30+ > instance ToSample Greet where
31+ > toSample = Just g
32+ >
33+ > where g = Greet "Hello, haskeller!"
34+ >
35+ > instance ToParam (QueryParam "capital" Bool) where
36+ > toParam _ =
37+ > DocQueryParam "capital"
38+ > ["true", "false"]
39+ > "Get the greeting message in uppercase (true) or not (false). Default is false."
40+ >
41+ > instance ToCapture (Capture "name" Text) where
42+ > toCapture _ = DocCapture "name" "name of the person to greet"
43+ >
44+ > instance ToCapture (Capture "greetid" Text) where
45+ > toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
46+ >
47+ > -- API specification
48+ > type TestApi =
49+ > "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet
50+ > :<|> "greet" :> RQBody Greet :> Post Greet
51+ > :<|> "delete" :> Capture "greetid" Text :> Delete
52+ >
53+ > testApi :: Proxy TestApi
54+ > testApi = Proxy
55+ >
56+ > -- Generate the Documentation's ADT
57+ > greetDocs :: API
58+ > greetDocs = docs testApi
59+ >
60+ > main :: IO ()
61+ > main = putStrLn $ markdown greetDocs
562license: BSD3
663license-file: LICENSE
764author: Alp Mestanogullari, Sönke Hahn, Julian K. Arni
@@ -11,6 +68,11 @@ category: Web
1168build-type: Simple
1269cabal-version: >=1.10
1370tested-with: GHC >= 7.8
71+homepage: http://haskell-servant.github.io/
72+Bug-reports: http://github.com/haskell-servant/servant-docs/issues
73+source-repository head
74+ type: git
75+ location: http://github.com/haskell-servant/servant-docs.git
1476
1577library
1678 exposed-modules:
@@ -27,11 +89,11 @@ library
2789 , unordered-containers
2890 hs-source-dirs: src
2991 default-language: Haskell2010
30− ghc-options: -O0 -Wall
92+ ghc-options: -Wall
3193
3294executable greet-docs
3395 main-is: greet.hs
3496 hs-source-dirs: example
35− ghc-options: -O0 -Wall
97+ ghc-options: -Wall
3698 build-depends: base, aeson, servant, servant-docs, text
3799 default-language: Haskell2010