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