Safe Haskell	None
Language	Haskell2010

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

newtype ApiDocs = ApiDocs (OMap Route Details)
data Details
- = Details (OMap Parameter Details)
- | Detail Text
class Renderable a where
- render :: ApiDocs -> a
type Parameter = Text
type Route = Text
newtype Json = Json {
- getJson :: Value
}
newtype Pretty ann = Pretty {
- getPretty :: Doc ann
}
newtype PlainText = PlainText {
- getPlainText :: Text
}

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 Methods showsPrec :: Int -> ApiDocs -> ShowS # show :: ApiDocs -> String # showList :: [ApiDocs] -> ShowS #
ToJSON ApiDocs Source #	Json instance for the endpoints hashmap
Instance details Defined in Servant.Docs.Simple.Render Methods toJSON :: ApiDocs -> Value # toEncoding :: ApiDocs -> Encoding # toJSONList :: [ApiDocs] -> Value # toEncodingList :: [ApiDocs] -> Encoding #

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 Methods showsPrec :: Int -> Details -> ShowS # show :: Details -> String # showList :: [Details] -> ShowS #
ToJSON Details Source #	Json instance for the parameter hashmap of each endpoint
Instance details Defined in Servant.Docs.Simple.Render Methods toJSON :: Details -> Value # toEncoding :: Details -> Encoding # toJSONList :: [Details] -> Value # toEncodingList :: [Details] -> Encoding #

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 Methods render :: ApiDocs -> PlainText Source #
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 getJson :: Value

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 getPretty :: Doc ann

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 getPlainText :: Text

Instances

Eq PlainText Source #
Instance details Defined in Servant.Docs.Simple.Render Methods (==) :: PlainText -> PlainText -> Bool # (/=) :: PlainText -> PlainText -> Bool #
Show PlainText Source #
Instance details Defined in Servant.Docs.Simple.Render Methods showsPrec :: Int -> PlainText -> ShowS # show :: PlainText -> String # showList :: [PlainText] -> ShowS #
Renderable PlainText Source #	Conversion to plaintext
Instance details Defined in Servant.Docs.Simple.Render Methods render :: ApiDocs -> PlainText Source #