git.iko.soy/typeable/servant
on v0.3.1 help sign in
typeable/servant/README.md
67 lines 2.1 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
31instance FromJSON Greet
32instance ToJSON Greet
34-- we provide a sample value for the 'Greet' type
35instance ToSample Greet where
36 toSample = Just g
38 where g = Greet "Hello, haskeller!"
40instance 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."
46instance ToCapture (Capture "name" Text) where
47 toCapture _ = DocCapture "name" "name of the person to greet"
49instance ToCapture (Capture "greetid" Text) where
50 toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
52-- API specification
53type TestApi =
54 "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet
55 :<|> "greet" :> RQBody Greet :> Post Greet
56 :<|> "delete" :> Capture "greetid" Text :> Delete
58testApi :: Proxy TestApi
59testApi = Proxy
61-- Generate the Documentation's ADT
62greetDocs :: API
63greetDocs = docs testApi
65main :: IO ()
66main = putStrLn $ markdown greetDocs
67```