servant-docs-0.13: generate API docs for your servant webservice
Safe HaskellSafe-Inferred
LanguageHaskell2010

Servant.Docs

Description

This module lets you get API docs for free. It lets you generate an API from the type that represents your API using docs:

docs :: HasDocs api => Proxy api -> API

Alternatively, if you wish to add one or more introductions to your documentation, use docsWithIntros:

docsWithIntros :: HasDocs api => [DocIntro] -> Proxy api -> API

You can then call markdown on the API value:

markdown :: API -> String

or define a custom pretty printer:

yourPrettyDocs :: API -> String -- or blaze-html's HTML, or ...

The only thing you'll need to do will be to implement some classes for your captures, get parameters and request or response bodies.

See example/greet.hs for an example.

Synopsis

HasDocs class and key functions

class HasDocs api where Source #

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

Methods

docsFor :: Proxy api -> (Endpoint, Action) -> DocOptions -> API Source #

Instances

Instances details
HasDocs EmptyAPI Source #

The generated docs for EmptyAPI are empty.

Instance details

Defined in Servant.Docs.Internal

HasDocs Raw Source # 
Instance details

Defined in Servant.Docs.Internal

(HasDocs (ToServantApi api), ErrorIfNoGeneric api) => HasDocs (NamedRoutes api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

(HasDocs a, HasDocs b) => HasDocs (a :<|> b :: Type) Source #

The generated docs for a :<|> b just appends the docs for a with the docs for b.

Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (a :<|> b) -> (Endpoint, Action) -> DocOptions -> API Source #

ReflectMethod method => HasDocs (NoContentVerb method :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

HasDocs api => HasDocs (Vault :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Vault :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol path, HasDocs api) => HasDocs (path :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (path :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs api => HasDocs (HttpVersion :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

(ToAuthInfo (BasicAuth realm usr), HasDocs api) => HasDocs (BasicAuth realm usr :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (BasicAuth realm usr :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol descr, KnownSymbol sym, HasDocs api) => HasDocs (Capture' (Description descr ': mods) sym a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Capture' (Description descr ': mods) sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs (Capture' mods sym a :> api) => HasDocs (Capture' (mod ': mods) sym a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Capture' (mod ': mods) sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol sym, ToCapture (Capture sym a), HasDocs api) => HasDocs (Capture' ('[] :: [Type]) sym a :> api :: Type) Source #

"books" :> Capture "isbn" Text will appear as books:isbn in the docs.

Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Capture' '[] sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol sym, ToCapture (CaptureAll sym a), HasDocs sublayout) => HasDocs (CaptureAll sym a :> sublayout :: Type) Source #

"books" :> CaptureAll "isbn" Text will appear as books:isbn in the docs.

Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (CaptureAll sym a :> sublayout) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol desc, HasDocs api) => HasDocs (Description desc :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Description desc :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol desc, HasDocs api) => HasDocs (Summary desc :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Summary desc :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(ToFragment (Fragment a), HasDocs api) => HasDocs (Fragment a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Fragment a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(ToHttpApiData a, ToSample a, KnownSymbol sym, HasDocs api) => HasDocs (Header' mods sym a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Header' mods sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs api => HasDocs (IsSecure :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

(KnownSymbol sym, ToParam (QueryFlag sym), HasDocs api) => HasDocs (QueryFlag sym :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (QueryFlag sym :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol sym, ToParam (QueryParam' mods sym a), HasDocs api) => HasDocs (QueryParam' mods sym a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (QueryParam' mods sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(KnownSymbol sym, ToParam (QueryParams sym a), HasDocs api) => HasDocs (QueryParams sym a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (QueryParams sym a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs api => HasDocs (RemoteHost :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

(ToSample a, AllMimeRender (ct ': cts) a, HasDocs api) => HasDocs (ReqBody' mods (ct ': cts) a :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (ReqBody' mods (ct ': cts) a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

(HasDocs api, Accept ctype) => HasDocs (StreamBody' mods framing ctype a :> api :: Type) Source #

TODO: this instance is incomplete.

Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (StreamBody' mods framing ctype a :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs api => HasDocs (WithResource res :> api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (WithResource res :> api) -> (Endpoint, Action) -> DocOptions -> API Source #

HasDocs api => HasDocs (WithNamedContext name context api :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (WithNamedContext name context api) -> (Endpoint, Action) -> DocOptions -> API Source #

(ToSample a, AllMimeRender (ct ': cts) a, KnownNat status, ReflectMethod method, AllHeaderSamples ls, GetHeaders (HList ls)) => HasDocs (Verb method status (ct ': cts) (Headers ls a) :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Verb method status (ct ': cts) (Headers ls a)) -> (Endpoint, Action) -> DocOptions -> API Source #

(ToSample a, AllMimeRender (ct ': cts) a, KnownNat status, ReflectMethod method) => HasDocs (Verb method status (ct ': cts) a :: Type) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Verb method status (ct ': cts) a) -> (Endpoint, Action) -> DocOptions -> API Source #

(Accept ct, KnownNat status, ReflectMethod method) => HasDocs (Stream method status framing ct a :: Type) Source #

TODO: mention the endpoint is streaming, its framing strategy

Also there are no samples.

TODO: AcceptFraming for content-type

Instance details

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (Stream method status framing ct a) -> (Endpoint, Action) -> DocOptions -> API Source #

docs :: HasDocs api => Proxy api -> API Source #

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

docs == docsWithOptions defaultDocOptions

pretty :: Proxy api -> Proxy (Pretty api) Source #

Prettify generated JSON documentation.

docs (pretty (Proxy :: Proxy MyAPI))

markdown :: API -> String Source #

Generate documentation in Markdown format for the given API.

This is equivalent to markdownWith defRenderingOptions.

Customising generated documentation

markdownWith :: RenderingOptions -> API -> String Source #

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
  

Since: 0.11.1

data RenderingOptions Source #

Customise how an API is converted into documentation.

Since: 0.11.1

Constructors

RenderingOptions 

Fields

Instances

Instances details
Show RenderingOptions Source # 
Instance details

Defined in Servant.Docs.Internal

defRenderingOptions :: RenderingOptions Source #

Default API generation options.

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

Since: 0.11.1

data ShowContentTypes Source #

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

Since: 0.11.1

Constructors

AllContentTypes

For each example, show each content type.

FirstContentType

For each example, show only one content type.

Instances

Instances details
Bounded ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Enum ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Read ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Show ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Eq ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Ord ShowContentTypes Source # 
Instance details

Defined in Servant.Docs.Internal

Generating docs with extra information

docsWith :: HasDocs api => DocOptions -> [DocIntro] -> ExtraInfo api -> Proxy api -> 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 api => [DocIntro] -> Proxy api -> API Source #

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

docsWithOptions :: HasDocs api => Proxy api -> DocOptions -> API Source #

Generate the docs for a given API that implements HasDocs.

newtype ExtraInfo api 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.

Instances

Instances details
Monoid (ExtraInfo a) Source # 
Instance details

Defined in Servant.Docs.Internal

Semigroup (ExtraInfo a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

(<>) :: ExtraInfo a -> ExtraInfo a -> ExtraInfo a #

sconcat :: NonEmpty (ExtraInfo a) -> ExtraInfo a #

stimes :: Integral b => b -> ExtraInfo a -> ExtraInfo a #

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

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"]
                                     ]

data DocOptions Source #

Documentation options.

Constructors

DocOptions 

Fields

Instances

Instances details
Show DocOptions Source # 
Instance details

Defined in Servant.Docs.Internal

defaultDocOptions :: DocOptions Source #

Default documentation options.

Classes you need to implement for your types

class ToSample a 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 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 ErrorMessage) that explains when you're supposed to get the corresponding response.

Minimal complete definition

Nothing

Methods

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

default toSamples :: (Generic a, GToSample (Rep a)) => Proxy a -> [(Text, a)] Source #

Instances

Instances details
ToSample All Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy All -> [(Text, All)] Source #

ToSample Any Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy Any -> [(Text, Any)] Source #

ToSample Ordering Source # 
Instance details

Defined in Servant.Docs.Internal

ToSample NoContent Source # 
Instance details

Defined in Servant.Docs.Internal

ToSample Bool Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy Bool -> [(Text, Bool)] Source #

ToSample a => ToSample (ZipList a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (First a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Last a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Dual a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Product a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Sum a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (NonEmpty a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Maybe a) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample [a] Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b) => ToSample (Either a b) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b) => ToSample (a, b) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Const a b) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c) => ToSample (a, b, c) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d) => ToSample (a, b, c, d) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e) => ToSample (a, b, c, d, e) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy (a, b, c, d, e) -> [(Text, (a, b, c, d, e))] Source #

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e, ToSample f) => ToSample (a, b, c, d, e, f) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy (a, b, c, d, e, f) -> [(Text, (a, b, c, d, e, f))] Source #

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e, ToSample f, ToSample g) => ToSample (a, b, c, d, e, f, g) Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy (a, b, c, d, e, f, g) -> [(Text, (a, b, c, d, e, f, g))] Source #

toSample :: forall a. ToSample a => Proxy a -> Maybe a Source #

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

noSamples :: [(Text, a)] Source #

No samples.

singleSample :: a -> [(Text, a)] Source #

Single sample without description.

samples :: [a] -> [(Text, a)] Source #

Samples without documentation.

sampleByteString :: forall ct cts a. (ToSample a, AllMimeRender (ct ': cts) a) => Proxy (ct ': cts) -> Proxy a -> [(MediaType, ByteString)] Source #

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

sampleByteStrings :: forall ct cts a. (ToSample a, AllMimeRender (ct ': cts) a) => Proxy (ct ': cts) -> Proxy a -> [(Text, MediaType, ByteString)] Source #

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

class ToParam t where Source #

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."

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"

ADTs to represent an API

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 .~ HTTP.methodPost
"POST" /foo

Instances

Instances details
Generic Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

Associated Types

type Rep Endpoint :: Type -> Type #

Methods

from :: Endpoint -> Rep Endpoint x #

to :: Rep Endpoint x -> Endpoint #

Show Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

Eq Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

Ord Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

Hashable Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

hashWithSalt :: Int -> Endpoint -> Int #

hash :: Endpoint -> Int #

type Rep Endpoint Source # 
Instance details

Defined in Servant.Docs.Internal

type Rep Endpoint = D1 ('MetaData "Endpoint" "Servant.Docs.Internal" "servant-docs-0.13-4Tq4f8zdMmV9jONgZBZEnf" 'False) (C1 ('MetaCons "Endpoint" 'PrefixI 'True) (S1 ('MetaSel ('Just "_path") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [String]) :*: S1 ('MetaSel ('Just "_method") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Method)))

defEndpoint :: Endpoint Source #

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

data API Source #

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

Instances

Instances details
Monoid API Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

mempty :: API #

mappend :: API -> API -> API #

mconcat :: [API] -> API #

Semigroup API Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

(<>) :: API -> API -> API #

sconcat :: NonEmpty API -> API #

stimes :: Integral b => b -> API -> API #

Show API Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> API -> ShowS #

show :: API -> String #

showList :: [API] -> ShowS #

Eq API Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

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

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 

data DocQueryParam Source #

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

data ParamKind Source #

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

Constructors

Normal 
List 
Flag 

Instances

Instances details
Show ParamKind Source # 
Instance details

Defined in Servant.Docs.Internal

Eq ParamKind Source # 
Instance details

Defined in Servant.Docs.Internal

Ord ParamKind Source # 
Instance details

Defined in Servant.Docs.Internal

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 

Instances

Instances details
Show DocNote Source # 
Instance details

Defined in Servant.Docs.Internal

Eq DocNote Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

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

Ord DocNote Source # 
Instance details

Defined in Servant.Docs.Internal

data DocIntro Source #

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

Constructors

DocIntro 

Fields

Instances

Instances details
Show DocIntro Source # 
Instance details

Defined in Servant.Docs.Internal

Eq DocIntro Source # 
Instance details

Defined in Servant.Docs.Internal

Ord DocIntro Source # 
Instance details

Defined in Servant.Docs.Internal

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

>>> defResponse
Response {_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 = []}

Instances

Instances details
Show Response Source # 
Instance details

Defined in Servant.Docs.Internal

Eq Response Source # 
Instance details

Defined in Servant.Docs.Internal

Ord Response Source # 
Instance details

Defined in Servant.Docs.Internal

defResponse :: Response Source #

Default response: status code 200, no response body.

Can be tweaked with four lenses.

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

data Action Source #

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.

Instances

Instances details
Show Action Source # 
Instance details

Defined in Servant.Docs.Internal

Eq Action Source # 
Instance details

Defined in Servant.Docs.Internal

Methods

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

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

Ord Action Source # 
Instance details

Defined in Servant.Docs.Internal

defAction :: Action Source #

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

Tweakable with lenses.

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

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