Safe Haskell	None
Language	Haskell2010

Servant.Docs.Internal

Contents

Instances

Synopsis

Documentation

data Method Source

Supported HTTP request methods

Constructors

DocDELETE	the DELETE method
DocGET	the GET method
DocPOST	the POST method
DocPUT	the PUT method

Instances

Eq Method
Ord Method
Show Method
Generic Method
Hashable Method
type Rep Method

data Endpoint Source

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 .~ DocPOST
POST /foo

Constructors

Endpoint
Fields _path :: [String] _method :: Method

Instances

Eq Endpoint
Ord Endpoint
Show Endpoint
Generic Endpoint
Hashable Endpoint
type Rep Endpoint

showPath :: [String] -> String Source

Render a path as a /-delimited string

defEndpoint :: Endpoint Source

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

Here's how you can modify it:

λ> defEndpoint
GET /
λ> defEndpoint & path <>~ ["foo"]
GET /foo
λ> defEndpoint & path <>~ ["foo"] & method .~ DocPOST
POST /foo

data API Source

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

Constructors

API
Fields _apiIntros :: [DocIntro] _apiEndpoints :: HashMap Endpoint Action

Instances

Eq API
Show API
Monoid API

emptyAPI :: API Source

An empty API

data DocCapture Source

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

Write a ToCapture instance for your captured types.

Constructors

DocCapture
Fields _capSymbol :: String _capDesc :: String

Instances

Eq DocCapture
Ord DocCapture
Show DocCapture

data DocQueryParam Source

A type to represent a GET 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

Constructors

DocQueryParam
Fields _paramName :: String _paramValues :: [String] _paramDesc :: String _paramKind :: ParamKind

Instances

Eq DocQueryParam
Ord DocQueryParam
Show DocQueryParam

data DocIntro Source

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

Constructors

DocIntro
Fields _introTitle :: String Appears above the intro blob _introBody :: [String] Each String is a paragraph.

Instances

Eq DocIntro
Ord DocIntro
Show DocIntro

data DocNote Source

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.

Constructors

DocNote
Fields _noteTitle :: String _noteBody :: [String]

Instances

Eq DocNote
Ord DocNote
Show DocNote

newtype ExtraInfo layout Source

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.

Constructors

ExtraInfo (HashMap Endpoint Action)

Instances

Monoid (ExtraInfo k a)

data ParamKind Source

Type of GET 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

Constructors

Normal
List
Flag

Instances

Eq ParamKind
Ord ParamKind
Show ParamKind

data Response Source

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 three lenses.

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

Constructors

Response
Fields _respStatus :: Int _respTypes :: [MediaType] _respBody :: [(Text, MediaType, ByteString)] _respHeaders :: [Header]

Instances

Eq Response
Ord Response
Show Response

defResponse :: Response Source

Default response: status code 200, no response body.

Can be tweaked with two lenses.

λ> defResponse
Response {_respStatus = 200, _respBody = Nothing}
λ> defResponse & respStatus .~ 204 & respBody .~ Just "[]"
Response {_respStatus = 204, _respBody = Just "[]"}

data Action Source

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

List of captures (captures)
List of GET 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.

Constructors

Action
Fields _captures :: [DocCapture] _headers :: [Text] _params :: [DocQueryParam] _notes :: [DocNote] _mxParams :: [(String, [DocQueryParam])] _rqtypes :: [MediaType] _rqbody :: [(MediaType, ByteString)] _response :: Response

Instances

Eq Action
Ord Action
Show Action

combineAction :: Action -> Action -> Action Source

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, body and content types from the very left.

defAction :: Action Source

single :: Endpoint -> Action -> API Source

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

apiIntros :: Lens' API [DocIntro] Source

apiEndpoints :: Lens' API (HashMap Endpoint Action) Source

path :: Lens' Endpoint [String] Source

method :: Lens' Endpoint Method Source

capSymbol :: Lens' DocCapture String Source

capDesc :: Lens' DocCapture String Source

paramValues :: Lens' DocQueryParam [String] Source

paramName :: Lens' DocQueryParam String Source

paramKind :: Lens' DocQueryParam ParamKind Source

paramDesc :: Lens' DocQueryParam String Source

introTitle :: Lens' DocIntro String Source

introBody :: Lens' DocIntro [String] Source

noteTitle :: Lens' DocNote String Source

noteBody :: Lens' DocNote [String] Source

respTypes :: Lens' Response [MediaType] Source

respStatus :: Lens' Response Int Source

respHeaders :: Lens' Response [Header] Source

respBody :: Lens' Response [(Text, MediaType, ByteString)] Source

rqtypes :: Lens' Action [MediaType] Source

rqbody :: Lens' Action [(MediaType, ByteString)] Source

response :: Lens' Action Response Source

params :: Lens' Action [DocQueryParam] Source

notes :: Lens' Action [DocNote] Source

mxParams :: Lens' Action [(String, [DocQueryParam])] Source

headers :: Lens' Action [Text] Source

captures :: Lens' Action [DocCapture] Source

docs :: HasDocs layout => Proxy layout -> API Source

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

type family IsIn endpoint api :: Constraint Source

Closed type family, check if endpoint is exactly within API.

Equations

IsIn e (sa :<\|> sb) = Or (IsIn e sa) (IsIn e sb)
IsIn (e :> sa) (e :> sb) = IsIn sa sb
IsIn e e = ()

extraInfo :: (IsIn endpoint layout, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo layout Source

Create an ExtraInfo that is garunteed 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 <>~ ["unicorns"]
                       & notes   <>~ [ DocNote "Title" ["This is some text"]
                                     , DocNote "Second secton" ["And some more"]
                                     ]

docsWith :: HasDocs layout => [DocIntro] -> ExtraInfo layout -> Proxy layout -> API Source

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.

docsWithIntros :: HasDocs layout => [DocIntro] -> Proxy layout -> API Source

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

class HasDocs layout where Source

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

Methods

docsFor :: Proxy layout -> (Endpoint, Action) -> API Source

Instances

HasDocs * Raw
(HasDocs * layout1, HasDocs * layout2) => HasDocs * ((:<\|>) layout1 layout2)	The generated docs for `a :<\|> b` just appends the docs for `a` with the docs for `b`.
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples [] ls, GetHeaders (HList ls)) => HasDocs (Get cts (Headers ls a))
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs * (Get cts a)
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples [] ls, GetHeaders (HList ls)) => HasDocs (Post cts (Headers ls a))
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs * (Post cts a)
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples [] ls, GetHeaders (HList ls)) => HasDocs (Delete cts (Headers ls a))
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs * (Delete cts a)
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples [] ls, GetHeaders (HList ls)) => HasDocs (Put cts (Headers ls a))
(ToSample * a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs * (Put cts a)
(ToSample k1 a b, IsNonEmpty cts, AllMimeRender cts b, HasDocs k sublayout, SupportedTypes cts) => HasDocs * ((:>) * k (ReqBody k cts a) sublayout)
(KnownSymbol sym, HasDocs k sublayout) => HasDocs * ((:>) * k (MatrixFlag sym) sublayout)
(KnownSymbol sym, HasDocs k sublayout) => HasDocs * ((:>) * k (MatrixParams k sym a) sublayout)
(KnownSymbol sym, ToParam * (MatrixParam k1 sym a), HasDocs k sublayout) => HasDocs * ((:>) * k (MatrixParam k sym a) sublayout)
(KnownSymbol sym, ToParam * (QueryFlag sym), HasDocs k sublayout) => HasDocs * ((:>) * k (QueryFlag sym) sublayout)
(KnownSymbol sym, ToParam * (QueryParams k1 sym a), HasDocs k sublayout) => HasDocs * ((:>) * k (QueryParams k sym a) sublayout)
(KnownSymbol sym, ToParam * (QueryParam k1 sym a), HasDocs k sublayout) => HasDocs * ((:>) * k (QueryParam k sym a) sublayout)
(KnownSymbol sym, HasDocs k sublayout) => HasDocs * ((:>) * k (Header sym a) sublayout)
(KnownSymbol sym, ToCapture * (Capture k1 sym a), HasDocs k sublayout) => HasDocs * ((:>) * k (Capture k sym a) sublayout)	`"books" :> Capture "isbn" Text` will appear as `books:isbn` in the docs.
(KnownSymbol path, HasDocs k sublayout) => HasDocs * ((:>) Symbol k path sublayout)

class ToSample a b | a -> b where Source

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 Greet where
  toSample _ = Just 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.

Minimal complete definition

toSample | toSamples

Methods

toSample :: Proxy a -> Maybe b Source

toSamples :: Proxy a -> [(Text, b)] Source

Instances

ToSample * a b => ToSample * (Headers ls a) b

class AllHeaderSamples ls where Source

Methods

allHeaderToSample :: Proxy ls -> [Header] Source

Instances

AllHeaderSamples [k] ([] k)
(ToByteString l, AllHeaderSamples [] ls, ToSample l l, KnownSymbol h) => AllHeaderSamples [] ((:) (Header h l) ls)

sampleByteString :: forall ctypes a b. (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(MediaType, ByteString)] Source

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

sampleByteStrings :: forall ctypes a b. (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(Text, MediaType, ByteString)] Source

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

class SupportedTypes list where Source

Generate a list of MediaType values describing the content types accepted by an API component.

Methods

supportedTypes :: Proxy list -> [MediaType] Source

Instances

SupportedTypes ([] *)
(Accept * ctype, SupportedTypes rest) => SupportedTypes ((:) * ctype rest)

class ToParam t where Source

The class that helps us automatically get documentation for GET parameters.

Example of an instance:

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

Methods

toParam :: Proxy t -> DocQueryParam Source

class ToCapture c where Source

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"

Methods

toCapture :: Proxy c -> DocCapture Source

markdown :: API -> String Source

Generate documentation in Markdown format for the given API.