git.iko.soy/servant
on issue-698 help sign in
servant/servant-docs/README.md
70 lines 2.3 kB history raw
1# servant-docs
3![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
5Generate 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**.
7## Example
9See [here](https://github.com/haskell-servant/servant/blob/master/servant-docs/example/greet.md) for the output of the following program.
11``` haskell
12{-# LANGUAGE DataKinds #-}
13{-# LANGUAGE PolyKinds #-}
14{-# LANGUAGE TypeFamilies #-}
15{-# LANGUAGE DeriveGeneric #-}
16{-# LANGUAGE TypeOperators #-}
17{-# LANGUAGE FlexibleInstances #-}
18{-# LANGUAGE OverloadedStrings #-}
20import Data.Proxy
21import Data.Text
22import Servant
24-- our type for a Greeting message
25data Greet = Greet { _msg :: Text }
26 deriving (Generic, Show)
28-- we get our JSON serialization for free. This will be used by the default
29-- 'MimeRender' instance for 'JSON'.
30instance FromJSON Greet
31instance ToJSON Greet
33-- We can also implement 'MimeRender' explicitly for additional formats.
34instance MimeRender PlainText Greet where
35 mimeRender Proxy (Greet s) = "<h1>" <> cs s <> "</h1>"
37-- we provide a sample value for the 'Greet' type
38instance ToSample Greet where
39 toSample = Just g
41 where g = Greet "Hello, haskeller!"
43instance ToParam (QueryParam "capital" Bool) where
44 toParam _ =
45 DocQueryParam "capital"
46 ["true", "false"]
47 "Get the greeting message in uppercase (true) or not (false). Default is false."
49instance ToCapture (Capture "name" Text) where
50 toCapture _ = DocCapture "name" "name of the person to greet"
52instance ToCapture (Capture "greetid" Text) where
53 toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
55-- API specification
56type TestApi =
57 "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
58 :<|> "greet" :> RQBody '[JSON] Greet :> Post '[JSON] Greet
59 :<|> "delete" :> Capture "greetid" Text :> Delete '[] ()
61testApi :: Proxy TestApi
62testApi = Proxy
64-- Generate the Documentation's ADT
65greetDocs :: API
66greetDocs = docs testApi
68main :: IO ()
69main = putStrLn $ markdown greetDocs
70```