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

Endpoints [Node "/hello/world"
                (Details [ Node "RequestBody" (Details [ Node "Format"
                                                              (Detail "': * () ('[] *)")
                                                       , Node "ContentType"
                                                              (Detail "()")
                                                       ])
                         , Node "RequestType" (Detail "'POST")
                         , Node "Response" (Details [ Node "Format"
                                                           (Detail "': * () ('[] *)")
                                                    , Node "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

data Details

Value representation; see Endpoints and Node documentation for a clearer picture

Constructors

Details [Node]

List of Parameter-Value pairs

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

Defined in Servant.Docs.Simple.Render

Methods

toJSON :: Details -> Value

toEncoding :: Details -> Encoding

toJSONList :: [Details] -> Value

toEncodingList :: [Details] -> Encoding

newtype Endpoints

Intermediate documentation structure, a linked-list of endpoints (Nodes)

API type:

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

Parsed into Endpoints:

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

For a breakdown reference Node

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

Constructors

Endpoints [Node]

Instances

Eq Endpoints

Defined in Servant.Docs.Simple.Render

Methods

(==) :: Endpoints -> Endpoints -> Bool

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

Show Endpoints

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Endpoints -> ShowS

show :: Endpoints -> String

showList :: [Endpoints] -> ShowS

ToJSON Endpoints

Defined in Servant.Docs.Simple.Render

Methods

toJSON :: Endpoints -> Value

toEncoding :: Endpoints -> Encoding

toJSONList :: [Endpoints] -> Value

toEncodingList :: [Endpoints] -> Encoding

data Node

Key-Value pair for endpoint parameters and their values

Example 1

An endpoint is represented as a node, with the route as its parameter and its Details as its value

Node "/users/get" <Details>

Example 2

Details of each endpoint can also be represented as nodes

Given the following:

Response '[()] ()

This can be interpreted as a Response parameter, with a value of 2 Details, Format and ContentType

In turn, this:

Format: '[()]

can be interpreted as a Format parameter with a value of '[()].

And so parsing Response '[()] () comes together as:

Node "Response"                                               --- Parameter
     (Details [ Node "Format"                   -- Parameter  ---
                     (Detail "': * () ('[] *)") -- Value         |
              , Node "ContentType"              -- Parameter     | Value
                     (Detail "()")              -- Value         |
              ])                                              ---

Constructors

Node

Fields

• Text

  Parameter name

• Details

  Parameter value(s)

Instances

Eq Node

Defined in Servant.Docs.Simple.Render

Methods

(==) :: Node -> Node -> Bool

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

Show Node

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Node -> ShowS

show :: Node -> String

showList :: [Node] -> ShowS

class Renderable a where

Convert Endpoints into different documentation formats

Methods

render :: Endpoints -> a

Instances

Renderable PlainText

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> PlainText

Renderable Json

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> Json

Renderable (Pretty ann)

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> Pretty ann

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

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> Json

newtype Pretty ann

Conversion to prettyprint

Constructors

Pretty

Fields

• getPretty :: Doc ann

Instances

Renderable (Pretty ann)

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> 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

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> PlainText