servant/servant-docs
2018-04-11 11:26:14 +03:00
..
example Replace all occurances of () with NoContent 2016-07-10 16:58:59 +02:00
include less OverlappingInstances noise 2016-01-04 13:09:11 -05:00
src/Servant Add description modifier helpers and parametrise Capture 2018-02-15 12:28:42 +02:00
test Add Servant.API.Modifiers to servant 2018-01-25 09:10:11 +02:00
.ghci servant-docs: add .ghci 2016-01-18 12:28:29 +01:00
CHANGELOG.md Add changelog and bump versions 2018-02-08 15:17:48 +02:00
docs.sh prepare merge 2015-04-20 11:19:48 +02:00
LICENSE Change copyright to servant contributors 2016-01-20 16:58:29 +01:00
README.md Import correct Servant module in README 2017-04-07 10:33:22 +10:00
servant-docs.cabal Allow base-compat-0.10.0 2018-04-11 11:26:14 +03:00
Setup.hs stylish haskell changes 2015-08-18 00:07:12 +02:00
tinc.yaml Use tinc on travis 2015-11-05 09:32:13 +08:00

servant-docs

servant

Generate API docs for your servant webservice. Feel free to also take a look at servant-pandoc which uses this package to target a broad range of output formats using the excellent pandoc.

Example

See here for the output of the following program.

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE OverloadedStrings #-}

import Data.Proxy
import Data.Text
import Servant.Docs

-- our type for a Greeting message
data Greet = Greet { _msg :: Text }
  deriving (Generic, Show)

-- we get our JSON serialization for free. This will be used by the default
-- 'MimeRender' instance for 'JSON'.
instance FromJSON Greet
instance ToJSON Greet

-- We can also implement 'MimeRender' explicitly for additional formats.
instance MimeRender PlainText Greet where
    mimeRender Proxy (Greet s) = "<h1>" <> cs s <> "</h1>"

-- we provide a sample value for the 'Greet' type
instance ToSample Greet where
  toSample = Just g

    where g = Greet "Hello, haskeller!"

instance ToParam (QueryParam "capital" Bool) where
  toParam _ =
    DocQueryParam "capital"
                  ["true", "false"]
                  "Get the greeting message in uppercase (true) or not (false). Default is false."

instance ToCapture (Capture "name" Text) where
  toCapture _ = DocCapture "name" "name of the person to greet"

instance ToCapture (Capture "greetid" Text) where
  toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"

-- API specification
type TestApi =
       "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
  :<|> "greet" :> RQBody '[JSON] Greet :> Post '[JSON] Greet
  :<|> "delete" :> Capture "greetid" Text :> Delete '[] ()

testApi :: Proxy TestApi
testApi = Proxy

-- Generate the Documentation's ADT
greetDocs :: API
greetDocs = docs testApi

main :: IO ()
main = putStrLn $ markdown greetDocs