servant-docs: generate API docs for your servant webservice

[ bsd3, library, program, servant, web ] [ Propose Tags ] [ Report a vulnerability ]

Library for generating API docs from a servant API definition.

Runnable example here.

CHANGELOG


[Skip to Readme]

Downloads

Versions [RSS] 0.2, 0.2.1, 0.3, 0.3.1, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.3.1, 0.4.4, 0.4.4.2, 0.4.4.3, 0.4.4.4, 0.4.4.5, 0.4.4.6, 0.4.4.7, 0.5, 0.6, 0.6.1, 0.7, 0.7.1, 0.8, 0.8.1, 0.9, 0.9.0.1, 0.9.1, 0.9.1.1, 0.10, 0.10.0.1, 0.11, 0.11.1, 0.11.2, 0.11.3, 0.11.4, 0.11.5, 0.11.6, 0.11.7, 0.11.8, 0.11.9, 0.12, 0.13, 0.13.1 (info)
Change log CHANGELOG.md
Dependencies aeson (>=1.4.1.0 && <3), aeson-pretty (>=0.8.5 && <0.9), base (>=4.14 && <4.21), base-compat (>=0.10.5 && <0.15), bytestring (>=0.10.8.1 && <0.13), case-insensitive (>=1.2.0.11 && <1.3), hashable (>=1.2.7.0 && <1.6), http-media (>=0.7.1.3 && <0.9), http-types (>=0.12.2 && <0.13), lens (>=4.17 && <5.4), servant (>=0.20.2 && <0.21), servant-docs, string-conversions (>=0.4.0.1 && <0.5), text (>=1.2.3.0 && <2.2), universe-base (>=1.1.1 && <1.2), unordered-containers (>=0.2.9.0 && <0.3) [details]
Tested with ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.8, ghc ==9.4.8, ghc ==9.6.4, ghc ==9.8.2, ghc ==9.10.1
License BSD-3-Clause
Copyright 2014-2016 Zalora South East Asia Pte Ltd, 2016-2019 Servant Contributors
Author Servant Contributors
Maintainer haskell-servant-maintainers@googlegroups.com
Category Servant, Web
Home page http://docs.servant.dev/
Bug tracker http://github.com/haskell-servant/servant/issues
Source repo head: git clone http://github.com/haskell-servant/servant.git
Uploaded by janus at 2024-08-30T02:31:35Z
Distributions LTSHaskell:0.13.1, NixOS:0.13.1, Stackage:0.13.1
Reverse Dependencies 24 direct, 29 indirect [details]
Executables greet-docs
Downloads 36731 total (133 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-08-30 [all 1 reports]

Readme for servant-docs-0.13.1

[back to package description]

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