Servant.Docs.Simple.Render

Renders the intermediate structure into common documentation formats

Example scripts

Generating plaintext/JSON documentation from api types

Writing our own rendering format

Example of rendering the intermediate structure

Intermediate structure

ApiDocs ( fromList [( "/hello/world",
                    , Details (fromList ([ ( "RequestBody"
                                           , Details (fromList ([ ( "Format"
                                                                  , Detail "': * () ('[] *)"
                                                                  )
                                                                , ( "ContentType"
                                                                  , Detail "()"
                                                                  )
                                                                ]))
                                           )
                                         , ( "RequestType"
                                           , Detail "'POST"
                                           )
                                         , ( "Response"
                                           , Details (fromList ([ ( "Format"
                                                                  , Detail "': * () ('[] *)"
                                                                  )
                                                                , ( "ContentType"
                                                                  , Detail "()"
                                                                  )
                                                                ]))
                                           )
                                         ]))
                    )])

JSON

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

Text

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

Documentation

newtype ApiDocs

Intermediate documentation structure, a hashmap of endpoints

API type:

  type API = "users" :> (      "update" :> Response '[()] ()
                          :<|> "get"    :> Response '[()] ()
                        )

Parsed into ApiDocs:

ApiDocs ( fromList [ ( "/users/update",
                     , Details (fromList ([ ( "Response"
                                            , Details (fromList ([ ( "Format"
                                                                   , Detail "': * () ('[] *)"
                                                                   )
                                                                 , ( "ContentType"
                                                                   , Detail "()"
                                                                   )
                                                                ]))
                                            )
                                          ]))
                     )
                   , ( "/users/get",
                     , Details (fromList ([ ( "Response"
                                            , Details (fromList ([ ( "Format"
                                                                   , Detail "': * () ('[] *)"
                                                                   )
                                                                 , ( "ContentType"
                                                                   , Detail "()"
                                                                   )
                                                                 ]))
                                            )
                                          ]))
                    )
                   ])

For more examples reference Test.Servant.Docs.Simple.Samples

Constructors

ApiDocs (OMap Route Details)

Instances

Eq ApiDocs

Defined in Servant.Docs.Simple.Render

Methods

(==) :: ApiDocs -> ApiDocs -> Bool

(/=) :: ApiDocs -> ApiDocs -> Bool

Show ApiDocs

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> ApiDocs -> ShowS

show :: ApiDocs -> String

showList :: [ApiDocs] -> ShowS

ToJSON ApiDocs

Json instance for the endpoints hashmap

Defined in Servant.Docs.Simple.Render

Methods

toJSON :: ApiDocs -> Value

toEncoding :: ApiDocs -> Encoding

toJSONList :: [ApiDocs] -> Value

toEncodingList :: [ApiDocs] -> Encoding

data Details

Details of the Api Route

Examples

Authentication: true

Can be interpreted as a Parameter (Authentication) and a Detail (true)

Response:
  Format: ...
  ContentType: ...

Can be interpreted as a Parameter (Response) and Details (Format (...), ContentType (...))

Constructors

Details (OMap Parameter Details)

OMap of Parameter-Details

Detail Text

Single Value

Instances

Eq Details

Defined in Servant.Docs.Simple.Render

Methods

(==) :: Details -> Details -> Bool

(/=) :: Details -> Details -> Bool

Show Details

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Details -> ShowS

show :: Details -> String

showList :: [Details] -> ShowS

ToJSON Details

Json instance for the parameter hashmap of each endpoint

Defined in Servant.Docs.Simple.Render

Methods

toJSON :: Details -> Value

toEncoding :: Details -> Encoding

toJSONList :: [Details] -> Value

toEncodingList :: [Details] -> Encoding

class Renderable a where

Convert ApiDocs into different documentation formats

Methods

render :: ApiDocs -> a

Instances

Renderable PlainText

Conversion to plaintext

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> PlainText

Renderable Json

Conversion to JSON using Data.Aeson

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Json

Renderable (Pretty ann)

Conversion to prettyprint

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Pretty ann

type Parameter = Text

Parameter names

type Route = Text

Route representation

newtype Json

Conversion to JSON using Data.Aeson

Constructors

Json

Fields

• getJson :: Value

Instances

Eq Json

Defined in Servant.Docs.Simple.Render

Methods

(==) :: Json -> Json -> Bool

(/=) :: Json -> Json -> Bool

Show Json

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Json -> ShowS

show :: Json -> String

showList :: [Json] -> ShowS

Renderable Json

Conversion to JSON using Data.Aeson

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Json

newtype Pretty ann

Conversion to prettyprint

Constructors

Pretty

Fields

• getPretty :: Doc ann

Instances

Renderable (Pretty ann)

Conversion to prettyprint

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Pretty ann

newtype PlainText

Conversion to plaintext

Constructors

PlainText

Fields

• getPlainText :: Text

Instances

Eq PlainText

Defined in Servant.Docs.Simple.Render

Methods

(==) :: PlainText -> PlainText -> Bool

(/=) :: PlainText -> PlainText -> Bool

Show PlainText

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> PlainText -> ShowS

show :: PlainText -> String

showList :: [PlainText] -> ShowS

Renderable PlainText

Conversion to plaintext

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> PlainText