generate API docs for your servant webservice

Version on this page:0.3.1
LTS Haskell 8.3:
Stackage Nightly 2017-02-26:0.10
Latest on Hackage:0.10
BSD3 licensed by Servant Contributors
Maintained by

Module documentation for 0.3.1

There are no documented modules for this package.



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.


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

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



There are no changes. Released as a part of servant suite.


  • Support GHC 8.0


  • Use throwError instead of throwE in documentation


  • Support for the HttpVersion, IsSecure, RemoteHost and Vault combinators
  • Support maximum samples setting with new DocOptions type (used by docsWithOptions and docsWith)
  • Remove redundant second parameter of ToSample
  • Add Generic-based default implementation for ToSample class
  • Add more ToSamples instances: Bool, Ordering, tuples (up to 7), [], Maybe, Either, Const, ZipList and some monoids
  • Move toSample out of ToSample class
  • Add a few helper functions to define toSamples
  • Remove matrix params.
  • Added support for Basic authentication


  • Delete now is like Get, Post, Put, and Patch and returns a response body
  • Allow for extra information to be added to the docs
  • Support content-type aware combinators of servant-0.4
  • Render endpoints in a canonical order (
  • Remove ToJSON superclass from ToSample
  • Split out Internal module
  • Add support for response headers
  • Allow ToSample to return a different type than it's arguments
  • Add Proxy argument to ToSample


  • Add the ability to display multiple responses, with some accompanying Text to describe the context in which we get the corresponding JSON.
  • Expose the headers lens
  • Represent an endpoint's path as [String] (previously String), fixing a corner case where the leading / would be missing.
comments powered byDisqus