Servant.Docs.Simple

Parse and render an API type, write documentation to file, stdout

Example script

Writing documentation to file

With the following language extensions

DataKinds
TypeApplications
TypeOperators

Using this script

module Main where

import Servant.API ((:>), Post, ReqBody)
import Servant.Docs.Simple (writeDocsJson, writeDocsPlainText)

-- Our API type
type API = "hello" :> "world" :> Request :> Response
type Request = ReqBody '[()] ()
type Response = Post '[()] ()

main :: IO ()
main = do
  -- Writes to the file $PWD/docsJson
  writeDocsJson @API "docs.json"

  -- Writes to the file $PWD/docsPlainText
  writeDocsPlainText @API "docs.txt"

Expected Output

Files should be generated relative to $PWD

$ ls | grep docs
docs.json
docs.txt

docs.json

{
    "/hello/world": {
        "Response": {
            "Format": "': * () ('[] *)",
            "ContentType": "()"
        },
        "RequestType": "'POST",
        "RequestBody": {
            "Format": "': * () ('[] *)",
            "ContentType": "()"
        }
    }
}

docs.txt

/hello/world:
RequestBody:
    Format: ': * () ('[] *)
    ContentType: ()
RequestType: 'POST
Response:
    Format: ': * () ('[] *)
    ContentType: ()

Documentation

document :: forall api. HasParsable api => PlainText

Convert API type into PlainText format

documentWith :: forall api a. (HasParsable api, Renderable a) => a

Convert API type into specified formats

stdoutJson :: forall api. HasParsable api => IO ()

Write documentation as JSON to stdout

stdoutPlainText :: forall api. HasParsable api => IO ()

Write documentation as PlainText to stdout

writeDocsJson :: forall api. HasParsable api => FilePath -> IO ()

Write documentation as JSON to file

writeDocsPlainText :: forall api. HasParsable api => FilePath -> IO ()

Write documentation as PlainText to file