Servant.Docs.Internal

Documentation

data Endpoint

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

Constructors

Endpoint

Fields

• _path :: [String]
• _method :: Method

Instances

Generic Endpoint

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

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> Endpoint -> ShowS

show :: Endpoint -> String

showList :: [Endpoint] -> ShowS

Eq Endpoint

Defined in Servant.Docs.Internal

Methods

(==) :: Endpoint -> Endpoint -> Bool

(/=) :: Endpoint -> Endpoint -> Bool

Ord Endpoint

Defined in Servant.Docs.Internal

Methods

compare :: Endpoint -> Endpoint -> Ordering

(<) :: Endpoint -> Endpoint -> Bool

(<=) :: Endpoint -> Endpoint -> Bool

(>) :: Endpoint -> Endpoint -> Bool

(>=) :: Endpoint -> Endpoint -> Bool

max :: Endpoint -> Endpoint -> Endpoint

min :: Endpoint -> Endpoint -> Endpoint

Hashable Endpoint

Defined in Servant.Docs.Internal

Methods

hashWithSalt :: Int -> Endpoint -> Int

hash :: Endpoint -> Int

type Rep Endpoint

Defined in Servant.Docs.Internal

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

showPath :: [String] -> String

Render a path as a /-delimited string

defEndpoint :: Endpoint

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

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

Monoid API

Defined in Servant.Docs.Internal

Methods

mempty :: API

mappend :: API -> API -> API

mconcat :: [API] -> API

Semigroup API

Defined in Servant.Docs.Internal

Methods

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

sconcat :: NonEmpty API -> API

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

Show API

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> API -> ShowS

show :: API -> String

showList :: [API] -> ShowS

Eq API

Defined in Servant.Docs.Internal

Methods

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

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

emptyAPI :: API

An empty API

data DocCapture

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

Show DocCapture

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocCapture -> ShowS

show :: DocCapture -> String

showList :: [DocCapture] -> ShowS

Eq DocCapture

Defined in Servant.Docs.Internal

Methods

(==) :: DocCapture -> DocCapture -> Bool

(/=) :: DocCapture -> DocCapture -> Bool

Ord DocCapture

Defined in Servant.Docs.Internal

Methods

compare :: DocCapture -> DocCapture -> Ordering

(<) :: DocCapture -> DocCapture -> Bool

(<=) :: DocCapture -> DocCapture -> Bool

(>) :: DocCapture -> DocCapture -> Bool

(>=) :: DocCapture -> DocCapture -> Bool

max :: DocCapture -> DocCapture -> DocCapture

min :: DocCapture -> DocCapture -> DocCapture

data DocQueryParam

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

Constructors

DocQueryParam

Fields

• _paramName :: String
• _paramValues :: [String]
• _paramDesc :: String
• _paramKind :: ParamKind

Instances

Show DocQueryParam

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocQueryParam -> ShowS

show :: DocQueryParam -> String

showList :: [DocQueryParam] -> ShowS

Eq DocQueryParam

Defined in Servant.Docs.Internal

Methods

(==) :: DocQueryParam -> DocQueryParam -> Bool

(/=) :: DocQueryParam -> DocQueryParam -> Bool

Ord DocQueryParam

Defined in Servant.Docs.Internal

Methods

compare :: DocQueryParam -> DocQueryParam -> Ordering

(<) :: DocQueryParam -> DocQueryParam -> Bool

(<=) :: DocQueryParam -> DocQueryParam -> Bool

(>) :: DocQueryParam -> DocQueryParam -> Bool

(>=) :: DocQueryParam -> DocQueryParam -> Bool

max :: DocQueryParam -> DocQueryParam -> DocQueryParam

min :: DocQueryParam -> DocQueryParam -> DocQueryParam

data DocFragment

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

Write a ToFragment instance for your fragment types.

Constructors

DocFragment

Fields

• _fragSymbol :: String
• _fragDesc :: String

Instances

Show DocFragment

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocFragment -> ShowS

show :: DocFragment -> String

showList :: [DocFragment] -> ShowS

Eq DocFragment

Defined in Servant.Docs.Internal

Methods

(==) :: DocFragment -> DocFragment -> Bool

(/=) :: DocFragment -> DocFragment -> Bool

Ord DocFragment

Defined in Servant.Docs.Internal

Methods

compare :: DocFragment -> DocFragment -> Ordering

(<) :: DocFragment -> DocFragment -> Bool

(<=) :: DocFragment -> DocFragment -> Bool

(>) :: DocFragment -> DocFragment -> Bool

(>=) :: DocFragment -> DocFragment -> Bool

max :: DocFragment -> DocFragment -> DocFragment

min :: DocFragment -> DocFragment -> DocFragment

combineFragment :: Maybe DocFragment -> Maybe DocFragment -> Maybe DocFragment

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

data DocIntro

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

Show DocIntro

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocIntro -> ShowS

show :: DocIntro -> String

showList :: [DocIntro] -> ShowS

Eq DocIntro

Defined in Servant.Docs.Internal

Methods

(==) :: DocIntro -> DocIntro -> Bool

(/=) :: DocIntro -> DocIntro -> Bool

Ord DocIntro

Defined in Servant.Docs.Internal

Methods

compare :: DocIntro -> DocIntro -> Ordering

(<) :: DocIntro -> DocIntro -> Bool

(<=) :: DocIntro -> DocIntro -> Bool

(>) :: DocIntro -> DocIntro -> Bool

(>=) :: DocIntro -> DocIntro -> Bool

max :: DocIntro -> DocIntro -> DocIntro

min :: DocIntro -> DocIntro -> DocIntro

data DocAuthentication

A type to represent Authentication information about an endpoint.

Constructors

DocAuthentication

Fields

• _authIntro :: String
• _authDataRequired :: String

Instances

Show DocAuthentication

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocAuthentication -> ShowS

show :: DocAuthentication -> String

showList :: [DocAuthentication] -> ShowS

Eq DocAuthentication

Defined in Servant.Docs.Internal

Methods

(==) :: DocAuthentication -> DocAuthentication -> Bool

(/=) :: DocAuthentication -> DocAuthentication -> Bool

Ord DocAuthentication

Defined in Servant.Docs.Internal

Methods

compare :: DocAuthentication -> DocAuthentication -> Ordering

(<) :: DocAuthentication -> DocAuthentication -> Bool

(<=) :: DocAuthentication -> DocAuthentication -> Bool

(>) :: DocAuthentication -> DocAuthentication -> Bool

(>=) :: DocAuthentication -> DocAuthentication -> Bool

max :: DocAuthentication -> DocAuthentication -> DocAuthentication

min :: DocAuthentication -> DocAuthentication -> DocAuthentication

data DocNote

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

Show DocNote

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocNote -> ShowS

show :: DocNote -> String

showList :: [DocNote] -> ShowS

Eq DocNote

Defined in Servant.Docs.Internal

Methods

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

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

Ord DocNote

Defined in Servant.Docs.Internal

Methods

compare :: DocNote -> DocNote -> Ordering

(<) :: DocNote -> DocNote -> Bool

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

(>) :: DocNote -> DocNote -> Bool

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

max :: DocNote -> DocNote -> DocNote

min :: DocNote -> DocNote -> DocNote

newtype ExtraInfo api

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 a)

Defined in Servant.Docs.Internal

Methods

mempty :: ExtraInfo a

mappend :: ExtraInfo a -> ExtraInfo a -> ExtraInfo a

mconcat :: [ExtraInfo a] -> ExtraInfo a

Semigroup (ExtraInfo a)

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

data DocOptions

Documentation options.

Constructors

DocOptions

Fields

• _maxSamples :: Int

  Maximum samples allowed.

Instances

Show DocOptions

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> DocOptions -> ShowS

show :: DocOptions -> String

showList :: [DocOptions] -> ShowS

defaultDocOptions :: DocOptions

Default documentation options.

data ParamKind

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

Show ParamKind

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> ParamKind -> ShowS

show :: ParamKind -> String

showList :: [ParamKind] -> ShowS

Eq ParamKind

Defined in Servant.Docs.Internal

Methods

(==) :: ParamKind -> ParamKind -> Bool

(/=) :: ParamKind -> ParamKind -> Bool

Ord ParamKind

Defined in Servant.Docs.Internal

Methods

compare :: ParamKind -> ParamKind -> Ordering

(<) :: ParamKind -> ParamKind -> Bool

(<=) :: ParamKind -> ParamKind -> Bool

(>) :: ParamKind -> ParamKind -> Bool

(>=) :: ParamKind -> ParamKind -> Bool

max :: ParamKind -> ParamKind -> ParamKind

min :: ParamKind -> ParamKind -> ParamKind

data Response

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 = []}

Constructors

Response

Fields

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

Instances

Show Response

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> Response -> ShowS

show :: Response -> String

showList :: [Response] -> ShowS

Eq Response

Defined in Servant.Docs.Internal

Methods

(==) :: Response -> Response -> Bool

(/=) :: Response -> Response -> Bool

Ord Response

Defined in Servant.Docs.Internal

Methods

compare :: Response -> Response -> Ordering

(<) :: Response -> Response -> Bool

(<=) :: Response -> Response -> Bool

(>) :: Response -> Response -> Bool

(>=) :: Response -> Response -> Bool

max :: Response -> Response -> Response

min :: Response -> Response -> Response

combineResponse :: Response -> Response -> Response

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.

defResponse :: Response

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

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.

Constructors

Action

Fields

• _authInfo :: [DocAuthentication]
• _captures :: [DocCapture]
• _headers :: [Header]
• _params :: [DocQueryParam]
• _fragment :: Maybe DocFragment
• _notes :: [DocNote]
• _mxParams :: [(String, [DocQueryParam])]
• _rqtypes :: [MediaType]
• _rqbody :: [(Text, MediaType, ByteString)]
• _response :: Response

Instances

Show Action

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> Action -> ShowS

show :: Action -> String

showList :: [Action] -> ShowS

Eq Action

Defined in Servant.Docs.Internal

Methods

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

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

Ord Action

Defined in Servant.Docs.Internal

Methods

compare :: Action -> Action -> Ordering

(<) :: Action -> Action -> Bool

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

(>) :: Action -> Action -> Bool

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

max :: Action -> Action -> Action

min :: Action -> Action -> Action

combineAction :: Action -> Action -> Action

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.

defAction :: Action

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

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

data ShowContentTypes

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

Bounded ShowContentTypes

Defined in Servant.Docs.Internal

Methods

minBound :: ShowContentTypes

maxBound :: ShowContentTypes

Enum ShowContentTypes

Defined in Servant.Docs.Internal

Methods

succ :: ShowContentTypes -> ShowContentTypes

pred :: ShowContentTypes -> ShowContentTypes

toEnum :: Int -> ShowContentTypes

fromEnum :: ShowContentTypes -> Int

enumFrom :: ShowContentTypes -> [ShowContentTypes]

enumFromThen :: ShowContentTypes -> ShowContentTypes -> [ShowContentTypes]

enumFromTo :: ShowContentTypes -> ShowContentTypes -> [ShowContentTypes]

enumFromThenTo :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes -> [ShowContentTypes]

Read ShowContentTypes

Defined in Servant.Docs.Internal

Methods

readsPrec :: Int -> ReadS ShowContentTypes

readList :: ReadS [ShowContentTypes]

readPrec :: ReadPrec ShowContentTypes

readListPrec :: ReadPrec [ShowContentTypes]

Show ShowContentTypes

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> ShowContentTypes -> ShowS

show :: ShowContentTypes -> String

showList :: [ShowContentTypes] -> ShowS

Eq ShowContentTypes

Defined in Servant.Docs.Internal

Methods

(==) :: ShowContentTypes -> ShowContentTypes -> Bool

(/=) :: ShowContentTypes -> ShowContentTypes -> Bool

Ord ShowContentTypes

Defined in Servant.Docs.Internal

Methods

compare :: ShowContentTypes -> ShowContentTypes -> Ordering

(<) :: ShowContentTypes -> ShowContentTypes -> Bool

(<=) :: ShowContentTypes -> ShowContentTypes -> Bool

(>) :: ShowContentTypes -> ShowContentTypes -> Bool

(>=) :: ShowContentTypes -> ShowContentTypes -> Bool

max :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes

min :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes

data RenderingOptions

Customise how an API is converted into documentation.

Since: 0.11.1

Constructors

RenderingOptions

Fields

• _requestExamples :: !ShowContentTypes

  How many content types to display for request body examples?

• _responseExamples :: !ShowContentTypes

  How many content types to display for response body examples?

• _notesHeading :: !(Maybe String)

  Optionally group all notes together under a common heading.

• _renderCurlBasePath :: !(Maybe String)

  Optionally render example curl requests under a common base path (e.g. `http://localhost:80`).

Instances

Show RenderingOptions

Defined in Servant.Docs.Internal

Methods

showsPrec :: Int -> RenderingOptions -> ShowS

show :: RenderingOptions -> String

showList :: [RenderingOptions] -> ShowS

defRenderingOptions :: RenderingOptions

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

authIntro :: Lens' DocAuthentication String

authDataRequired :: Lens' DocAuthentication String

maxSamples :: Iso' DocOptions Int

apiIntros :: Lens' API [DocIntro]

apiEndpoints :: Lens' API (HashMap Endpoint Action)

path :: Lens' Endpoint [String]

method :: Lens' Endpoint Method

capSymbol :: Lens' DocCapture String

capDesc :: Lens' DocCapture String

paramValues :: Lens' DocQueryParam [String]

paramName :: Lens' DocQueryParam String

paramKind :: Lens' DocQueryParam ParamKind

paramDesc :: Lens' DocQueryParam String

fragSymbol :: Lens' DocFragment String

fragDesc :: Lens' DocFragment String

introTitle :: Lens' DocIntro String

introBody :: Lens' DocIntro [String]

noteTitle :: Lens' DocNote String

noteBody :: Lens' DocNote [String]

respTypes :: Lens' Response [MediaType]

respStatus :: Lens' Response Int

respHeaders :: Lens' Response [Header]

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

rqtypes :: Lens' Action [MediaType]

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

response :: Lens' Action Response

params :: Lens' Action [DocQueryParam]

notes :: Lens' Action [DocNote]

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

headers :: Lens' Action [Header]

fragment :: Lens' Action (Maybe DocFragment)

captures :: Lens' Action [DocCapture]

authInfo :: Lens' Action [DocAuthentication]

responseExamples :: Lens' RenderingOptions ShowContentTypes

requestExamples :: Lens' RenderingOptions ShowContentTypes

renderCurlBasePath :: Lens' RenderingOptions (Maybe String)

notesHeading :: Lens' RenderingOptions (Maybe String)

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

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

docs == docsWithOptions defaultDocOptions

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

Generate the docs for a given API that implements HasDocs.

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

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

docsWith :: HasDocs api => DocOptions -> [DocIntro] -> ExtraInfo api -> Proxy api -> API

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

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

class HasDocs api where

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

Methods

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

Instances

HasDocs EmptyAPI

The generated docs for EmptyAPI are empty.

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy EmptyAPI -> (Endpoint, Action) -> DocOptions -> API

HasDocs Raw

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy Raw -> (Endpoint, Action) -> DocOptions -> API

(HasDocs (ToServantApi api), ErrorIfNoGeneric api) => HasDocs (NamedRoutes api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

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

Defined in Servant.Docs.Internal

Methods

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

ReflectMethod method => HasDocs (NoContentVerb method :: Type)

Defined in Servant.Docs.Internal

Methods

docsFor :: Proxy (NoContentVerb method) -> (Endpoint, Action) -> DocOptions -> API

(KnownSymbol path, HasDocs api) => HasDocs (path :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (HttpVersion :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

(ToAuthInfo (BasicAuth realm usr), HasDocs api) => HasDocs (BasicAuth realm usr :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

HasDocs (Capture' mods sym a :> api) => HasDocs (Capture' (mod ': mods) sym a :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

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

Defined in Servant.Docs.Internal

Methods

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

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

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

Defined in Servant.Docs.Internal

Methods

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

(KnownSymbol desc, HasDocs api) => HasDocs (Description desc :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

(KnownSymbol desc, HasDocs api) => HasDocs (Summary desc :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

(ToFragment (Fragment a), HasDocs api) => HasDocs (Fragment a :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (IsSecure :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

(KnownSymbol sym, ToParam (QueryFlag sym), HasDocs api) => HasDocs (QueryFlag sym :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

(KnownSymbol sym, ToParam (QueryParams sym a), HasDocs api) => HasDocs (QueryParams sym a :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (RemoteHost :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

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

TODO: this instance is incomplete.

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (WithResource res :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (Vault :> api :: Type)

Defined in Servant.Docs.Internal

Methods

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

HasDocs api => HasDocs (WithNamedContext name context api :: Type)

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

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

Defined in Servant.Docs.Internal

Methods

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

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

TODO: mention the endpoint is streaming, its framing strategy

Also there are no samples.

TODO: AcceptFraming for content-type

Defined in Servant.Docs.Internal

Methods

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

class ToSample a where

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

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

Instances

ToSample All

Defined in Servant.Docs.Internal

Methods

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

ToSample Any

Defined in Servant.Docs.Internal

Methods

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

ToSample Ordering

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy Ordering -> [(Text, Ordering)]

ToSample NoContent

Defined in Servant.Docs.Internal

Methods

toSamples :: Proxy NoContent -> [(Text, NoContent)]

ToSample Bool

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (ZipList a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (First a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Last a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Dual a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Product a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Sum a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (NonEmpty a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Maybe a)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample [a]

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b) => ToSample (Either a b)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b) => ToSample (a, b)

Defined in Servant.Docs.Internal

Methods

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

ToSample a => ToSample (Const a b)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c) => ToSample (a, b, c)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d) => ToSample (a, b, c, d)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e) => ToSample (a, b, c, d, e)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e, ToSample f) => ToSample (a, b, c, d, e, f)

Defined in Servant.Docs.Internal

Methods

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

(ToSample a, ToSample b, ToSample c, ToSample d, ToSample e, ToSample f, ToSample g) => ToSample (a, b, c, d, e, f, g)

Defined in Servant.Docs.Internal

Methods

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

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

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

noSamples :: [(Text, a)]

No samples.

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

Single sample without description.

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

Samples without documentation.

defaultSamples :: forall a. (Generic a, GToSample (Rep a)) => Proxy a -> [(Text, a)]

Default sample Generic-based inputs/outputs.

class GToSample t where

ToSample for Generics.

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

Methods

gtoSamples :: proxy t -> [(Text, t x)]

Instances

GToSample (U1 :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy U1 -> [(Text, U1 x)]

GToSample (V1 :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy V1 -> [(Text, V1 x)]

(GToSample p, GToSample q) => GToSample (p :*: q :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy (p :*: q) -> [(Text, (p :*: q) x)]

(GToSample p, GToSample q) => GToSample (p :+: q :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy (p :+: q) -> [(Text, (p :+: q) x)]

ToSample a => GToSample (K1 i a :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy (K1 i a) -> [(Text, K1 i a x)]

GToSample f => GToSample (M1 i a f :: k -> Type)

Defined in Servant.Docs.Internal

Methods

gtoSamples :: forall proxy (x :: k0). proxy (M1 i a f) -> [(Text, M1 i a f x)]

class AllHeaderSamples ls where

Methods

allHeaderToSample :: Proxy ls -> [Header]

Instances

AllHeaderSamples ('[] :: [k])

Defined in Servant.Docs.Internal

Methods

allHeaderToSample :: Proxy '[] -> [Header]

(ToHttpApiData l, AllHeaderSamples ls, ToSample l, KnownSymbol h) => AllHeaderSamples (Header h l ': ls :: [Type])

Defined in Servant.Docs.Internal

Methods

allHeaderToSample :: Proxy (Header h l ': ls) -> [Header0]

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

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

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

class ToParam t where

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

Methods

toParam :: Proxy t -> DocQueryParam

class ToCapture c where

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

class ToAuthInfo a where

The class that helps us get documentation for authenticated endpoints

Methods

toAuthInfo :: Proxy a -> DocAuthentication

class ToFragment t where

The class that helps us get documentation for URL fragments.

Example of an instance:

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

Methods

toFragment :: Proxy t -> DocFragment

markdown :: API -> String

Generate documentation in Markdown format for the given API.

This is equivalent to markdownWith defRenderingOptions.

markdownWith :: RenderingOptions -> API -> String

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

Instances

>>> :set -XOverloadedStrings