servant-docs

generate API docs for your servant webservice

http://haskell-servant.readthedocs.org/

Version on this page:0.11.2@rev:5
LTS Haskell 22.39:0.13.1
Stackage Nightly 2024-10-29:0.13.1
Latest on Hackage:0.13.1

See all snapshots servant-docs appears in

BSD-3-Clause licensed by Servant Contributors
Maintained by [email protected]
This version can be pinned in stack with:servant-docs-0.11.2@sha256:00841ea371eabae87f1aebf93eaebd132eb1a517e5a926b952e528a5f8306481,3381

Module documentation for 0.11.2

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

Changes

The latest version of this document is on GitHub. Changelog for servant package contains significant entries for all core packages.

0.11.2

  • Allow servant-0.13:
    • Doesn’t have instances for streaming.
    • Servant.API.Modifiers extra information isn’t used.

0.11.1

  • Export DocAuthentication and related lenses.
  • Make defAction’s documentation visible in Haddock documentation.
  • Add a markdown header for the Headers an endpoint is sensitive to.
  • Document the HTTP Method the parameters of an endpoint belong to (rather than assuming GET for all of them).
  • Content type of sample response body is also displayed.
  • Can now customise various aspects of how the document is produced using markdownWith and RenderingOptions:
    • How many content-types for each example are shown
    • Whether notes should be grouped together under their own header.

0.11

  • changed the type of rqbody.

0.10

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

0.7.1

  • Support GHC 8.0

0.7

  • Use throwError instead of throwE in documentation

0.5

  • 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

0.4

  • 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 (https://github.com/haskell-servant/servant-docs/pull/15)
  • 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

0.3

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