Servant.Docs.Internal

An Endpoint type that holds the path and the method.

Gets used as the key in the API hashmap. Modify defEndpoint or any Endpoint value you want using the path and method lenses to tweak.

>>> defEndpoint"GET" /

>>> defEndpoint & path <>~ ["foo"]"GET" /foo

>>> defEndpoint & path <>~ ["foo"] & method .~ HTTP.methodPost"POST" /foo

Render a path as a /-delimited string

An Endpoint whose path is `"/"` and whose method is GET

Here's how you can modify it:

>>> defEndpoint"GET" /

>>> defEndpoint & path <>~ ["foo"]"GET" /foo

>>> defEndpoint & path <>~ ["foo"] & method .~ HTTP.methodPost"POST" /foo

Our API documentation type, a product of top-level information and a good old hashmap from Endpoint to Action

An empty API

A type to represent captures. Holds the name of the capture and a description.

Write a ToCapture instance for your captured types.

A type to represent a GET (or other possible Method) parameter from the Query String. Holds its name, the possible values (leave empty if there isn't a finite number of them), and a description of how it influences the output or behavior.

Write a ToParam instance for your GET parameter types

A type to represent fragment. Holds the name of the fragment and its description.

Write a ToFragment instance for your fragment types.

There should be at most one Fragment per API endpoint. So here we are keeping the first occurrence.

An introductory paragraph for your documentation. You can pass these to docsWithIntros.

A type to represent Authentication information about an endpoint.

A type to represent extra notes that may be attached to an Action.

This is intended to be used when writing your own HasDocs instances to add extra sections to your endpoint's documentation.

Type of extra information that a user may wish to "union" with their documentation.

These are intended to be built using extraInfo. Multiple ExtraInfo may be combined with the monoid instance.

Documentation options.

Default documentation options.

Type of GET (or other Method) parameter:

• Normal corresponds to QueryParam, i.e your usual GET parameter

• List corresponds to QueryParams, i.e GET parameters with multiple values

• Flag corresponds to QueryFlag, i.e a value-less GET parameter

A type to represent an HTTP response. Has an Int status, a list of possible MediaTypes, and a list of example ByteString response bodies. Tweak defResponse using the respStatus, respTypes and respBody lenses if you want.

If you want to respond with a non-empty response body, you'll most likely want to write a ToSample instance for the type that'll be represented as encoded data in the response.

Can be tweaked with four lenses.

>>> defResponseResponse {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}

>>> defResponse & respStatus .~ 204 & respBody .~ [("If everything goes well", "application/json", "{ \"status\": \"ok\" }")]Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well",application/json,"{ \"status\": \"ok\" }")], _respHeaders = []}

Combine two Responses, we can't make a monoid because merging Status breaks the laws.

As such, we invent a non-commutative, left associative operation combineResponse to mush two together taking the status from the very left.

Default response: status code 200, no response body.

Can be tweaked with four lenses.

>>> defResponseResponse {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}

>>> defResponse & respStatus .~ 204Response {_respStatus = 204, _respTypes = [], _respBody = [], _respHeaders = []}

A datatype that represents everything that can happen at an endpoint, with its lenses:

• List of captures (captures)

• List of GET (or other Method) parameters (params)

• What the request body should look like, if any is requested (rqbody)

• What the response should be if everything goes well (response)

You can tweak an Action (like the default defAction) with these lenses to transform an action and add some information to it.

Combine two Actions, we can't make a monoid as merging Response breaks the laws.

As such, we invent a non-commutative, left associative operation combineAction to mush two together taking the response from the very left.

Default Action. Has no captures, no query params, expects no request body (rqbody) and the typical response is defResponse.

Tweakable with lenses.

>>> defActionAction {_authInfo = [], _captures = [], _headers = [], _params = [], _fragment = Nothing, _notes = [], _mxParams = [], _rqtypes = [], _rqbody = [], _response = Response {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}}

>>> defAction & response.respStatus .~ 201Action {_authInfo = [], _captures = [], _headers = [], _params = [], _fragment = Nothing, _notes = [], _mxParams = [], _rqtypes = [], _rqbody = [], _response = Response {_respStatus = 201, _respTypes = [], _respBody = [], _respHeaders = []}}

Create an API that's comprised of a single endpoint. API is a Monoid, so combine multiple endpoints with mappend or <>.

How many content-types for each example should be shown?

Customise how an API is converted into documentation.

Default API generation options.

All content types are shown for both requestExamples and responseExamples; notesHeading is set to Nothing (i.e. un-grouped).

Generate the docs for a given API that implements HasDocs. This is the default way to create documentation.

docs == docsWithOptions defaultDocOptions

Generate the docs for a given API that implements HasDocs.

Create an ExtraInfo that is guaranteed to be within the given API layout.

The safety here is to ensure that you only add custom documentation to an endpoint that actually exists within your API.

extra :: ExtraInfo TestApi
extra =
    extraInfo (Proxy :: Proxy ("greet" :> Capture "greetid" Text :> Delete)) $
             defAction & headers <>~ [("X-Num-Unicorns", 1)]
                       & notes   <>~ [ DocNote "Title" ["This is some text"]
                                     , DocNote "Second section" ["And some more"]
                                     ]

Generate documentation given some extra introductions (in the form of DocInfo) and some extra endpoint documentation (in the form of ExtraInfo.

The extra introductions will be prepended to the top of the documentation, before the specific endpoint documentation. The extra endpoint documentation will be "unioned" with the automatically generated endpoint documentation.

You are expected to build up the ExtraInfo with the Monoid instance and extraInfo.

If you only want to add an introduction, use docsWithIntros.

Generate the docs for a given API that implements HasDocs with any number of introduction(s)

The class that abstracts away the impact of API combinators on documentation generation.

The class that lets us display a sample input or output in the supported content-types when generating documentation for endpoints that either:

• expect a request body, or

• return a non empty response body

Example of an instance:

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE OverloadedStrings #-}

import Data.Aeson
import Data.Text
import GHC.Generics

data Greet = Greet { _msg :: Text }
  deriving (Generic, Show)

instance FromJSON Greet
instance ToJSON Greet

instance ToSample Greet where
  toSamples _ = singleSample g

    where g = Greet "Hello, haskeller!"

You can also instantiate this class using toSamples instead of toSample: it lets you specify different responses along with some context (as Text) that explains when you're supposed to get the corresponding response.

Sample input or output (if there is at least one).

No samples.

Single sample without description.

Samples without documentation.

Default sample Generic-based inputs/outputs.

ToSample for Generics.

Note: we use combinators from Universe.Data.Helpers for more productive sample generation.

Synthesise a sample value of a type, encoded in the specified media types.

Synthesise a list of sample values of a particular type, encoded in the specified media types.

The class that helps us automatically get documentation for GET (or other Method) parameters.

Example of an instance:

instance ToParam (QueryParam' mods "capital" Bool) where
  toParam _ =
    DocQueryParam "capital"
                  ["true", "false"]
                  "Get the greeting message in uppercase (true) or not (false). Default is false."

The class that helps us automatically get documentation for URL captures.

Example of an instance:

instance ToCapture (Capture "name" Text) where
  toCapture _ = DocCapture "name" "name of the person to greet"

The class that helps us get documentation for authenticated endpoints

The class that helps us get documentation for URL fragments.

Example of an instance:

instance ToFragment (Fragment a) where
  toFragment _ = DocFragment "fragment" "fragment description"

Generate documentation in Markdown format for the given API.

This is equivalent to markdownWith defRenderingOptions.

Generate documentation in Markdown format for the given API using the specified options.

These options allow you to customise aspects such as:

• Choose how many content-types for each request body example are shown with requestExamples.

• Choose how many content-types for each response body example are shown with responseExamples.

For example, to only show the first content-type of each example:

  markdownWith (defRenderingOptions
                  & requestExamples  .~ FirstContentType
                  & responseExamples .~ FirstContentType )
               myAPI