servant-docs-simple-0.1.0.0: Generate documentation via TypeRep for Servant API
Safe HaskellNone
LanguageHaskell2010

Servant.Docs.Simple.Render

Description

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: ()
Synopsis

Documentation

data Details Source #

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

Constructors

Details [Node]

List of Parameter-Value pairs

Detail Text

Single Value

Instances

Instances details
Eq Details Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

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

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

Show Details Source # 
Instance details

Defined in Servant.Docs.Simple.Render

ToJSON Details Source # 
Instance details

Defined in Servant.Docs.Simple.Render

newtype Endpoints Source #

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

Instances details
Eq Endpoints Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Show Endpoints Source # 
Instance details

Defined in Servant.Docs.Simple.Render

ToJSON Endpoints Source # 
Instance details

Defined in Servant.Docs.Simple.Render

data Node Source #

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

Instances

Instances details
Eq Node Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

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

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

Show Node Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Node -> ShowS #

show :: Node -> String #

showList :: [Node] -> ShowS #

class Renderable a where Source #

Convert Endpoints into different documentation formats

Methods

render :: Endpoints -> a Source #

Instances

Instances details
Renderable PlainText Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Renderable Json Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Renderable (Pretty ann) Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> Pretty ann Source #

newtype Json Source #

Conversion to JSON using Data.Aeson

Constructors

Json 

Fields

Instances

Instances details
Eq Json Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

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

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

Show Json Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

showsPrec :: Int -> Json -> ShowS #

show :: Json -> String #

showList :: [Json] -> ShowS #

Renderable Json Source # 
Instance details

Defined in Servant.Docs.Simple.Render

newtype Pretty ann Source #

Conversion to prettyprint

Constructors

Pretty 

Fields

Instances

Instances details
Renderable (Pretty ann) Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: Endpoints -> Pretty ann Source #

newtype PlainText Source #

Conversion to plaintext

Constructors

PlainText 

Fields

Instances

Instances details
Eq PlainText Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Show PlainText Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Renderable PlainText Source # 
Instance details

Defined in Servant.Docs.Simple.Render