servant-docs-simple-0.2.0.0: Generate endpoints overview 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

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

Documentation

newtype ApiDocs Source #

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 Source # 
Instance details

Defined in Servant.Docs.Simple.Render

Methods

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

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

Show ApiDocs Source # 
Instance details

Defined in Servant.Docs.Simple.Render

ToJSON ApiDocs Source #

Json instance for the endpoints hashmap

Instance details

Defined in Servant.Docs.Simple.Render

data Details Source #

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

Json instance for the parameter hashmap of each endpoint

Instance details

Defined in Servant.Docs.Simple.Render

class Renderable a where Source #

Convert ApiDocs into different documentation formats

Methods

render :: ApiDocs -> a Source #

Instances
Renderable PlainText Source #

Conversion to plaintext

Instance details

Defined in Servant.Docs.Simple.Render

Renderable Json Source #

Conversion to JSON using Data.Aeson

Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Json Source #

Renderable (Pretty ann) Source #

Conversion to prettyprint

Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Pretty ann Source #

type Parameter = Text Source #

Parameter names

type Route = Text Source #

Route representation

newtype Json Source #

Conversion to JSON using Data.Aeson

Constructors

Json 

Fields

Instances
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 #

Conversion to JSON using Data.Aeson

Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Json Source #

newtype Pretty ann Source #

Conversion to prettyprint

Constructors

Pretty 

Fields

Instances
Renderable (Pretty ann) Source #

Conversion to prettyprint

Instance details

Defined in Servant.Docs.Simple.Render

Methods

render :: ApiDocs -> Pretty ann Source #

newtype PlainText Source #

Conversion to plaintext

Constructors

PlainText 

Fields

Instances
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 #

Conversion to plaintext

Instance details

Defined in Servant.Docs.Simple.Render