servant-docs

generate API docs for your servant webservice

http://docs.servant.dev/

Version on this page:0.13@rev:4
LTS Haskell 22.39:0.13.1
Stackage Nightly 2024-10-31: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.13@sha256:555b48441a3063b2864ba3e3337ee5606064f04b5f927025439374f4397da09a,3413

Module documentation for 0.13

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 DeriveGeneric #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE TypeOperators #-}

import Data.Aeson (FromJSON, ToJSON)
import Data.Proxy (Proxy (..))
import Data.String.Conversions (cs)
import Data.Text (Text)
import GHC.Generics (Generic)
import Servant.API
  ( (:<|>),
    (:>),
    Capture,
    Delete,
    Get,
    JSON,
    MimeRender,
    PlainText,
    Post,
    QueryParam,
    ReqBody,
    mimeRender,
  )
import Servant.Docs
  ( API,
    DocCapture (..),
    DocQueryParam (..),
    ParamKind (..),
    ToCapture,
    ToParam,
    ToSample,
    docs,
    markdown,
    singleSample,
    toCapture,
    toParam,
    toSamples,
  )

-- 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
instance ToSample ()

-- 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
  toSamples _ = singleSample 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."
                  Normal

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" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet
  :<|> "delete" :> Capture "greetid" Text :> Delete '[JSON] ()

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

  • WithResource combinator for Servant-managed resources. #1630

    For servant-docs, this meant the addition of instance HasDocs api => HasDocs (WithResource res :> api)

  • Compatibility with GHC series 9.2, 9.4, 9.6

0.12

Significant changes

  • Generate sample cURL requests (#1401). Breaking change: requires sample header values to be supplied with headers.

0.11.9

Significant changes

  • Use Capture Description if available (#1423).

Other changes

  • Support GHC-9.0.1.
  • Bump bytestring and lens dependencies.

0.11.8

Significant changes

  • Support Fragment combinator.

0.11.7

Significant changes

  • Add instance for ToSample NonEmpty

Other changes

  • Bump “tested-with” ghc versions
  • Fix servant-docs code sample in README

0.11.5

  • Add NoContentVerb #1028 #1219 #1228

    The NoContent API endpoints should now use NoContentVerb combinator. The API type changes are usually of the kind

    - :<|> PostNoContent '[JSON] NoContent
    + :<|> PostNoContent
    

    i.e. one doesn’t need to specify the content-type anymore. There is no content.

  • Capture can be Lenient #1155 #1156

    You can specify a lenient capture as

    :<|> "capture-lenient"  :> Capture' '[Lenient] "foo" Int :> GET
    

    which will make the capture always succeed. Handlers will be of the type Either String CapturedType, where Left err represents the possible parse failure.

  • servant-docs Merge documentation from duplicate routes #1240 #1241

    Servant supports defining the same route multiple times with different content-types and result-types, but servant-docs was only documenting the first of copy of such duplicated routes. It now combines the documentation from all the copies.

    Unfortunately, it is not yet possible for the documentation to specify multiple status codes.

  • servant-docs Prevent race-conditions in testing #1194

0.11.4

  • Drop dependency on control-monad-omega in favor of Data.Universe.Helpers from universe-base.

0.11.3

  • Support servant-0.15
    • Instances for ‘Stream’ and ‘StreamBody’

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.