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 && <1.6), aeson-pretty (>=0.8.5 && <0.9), base (>=4.9 && <4.15), base-compat (>=0.10.5 && <0.12), bytestring (>=0.10.8.1 && <0.11), case-insensitive (>=1.2.0.11 && <1.3), hashable (>=1.2.7.0 && <1.4), http-media (>=0.7.1.3 && <0.9), http-types (>=0.12.2 && <0.13), lens (>=4.17 && <4.20), servant (>=0.18 && <0.19), servant-docs, string-conversions (>=0.4.0.1 && <0.5), text (>=1.2.3.0 && <1.3), universe-base (>=1.1.1 && <1.2), unordered-containers (>=0.2.9.0 && <0.3) [details]
Tested with ghc ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.5 || ==8.8.3 || ==8.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 MatthiasFischmann at 2020-09-01T12:26:00Z
Distributions LTSHaskell:0.13.1, NixOS:0.13.1, Stackage:0.13.1
Reverse Dependencies 24 direct, 29 indirect [details]
Executables greet-docs
Downloads 36656 total (136 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 2020-09-01 [all 1 reports]

Readme for servant-docs-0.11.6

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