servant-docs/README.md · typeable/servant

git.iko.soy/typeable/servant

typeable/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.Docs

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```