Safe Haskell	None
Language	Haskell2010

Servant.Docs.Internal

Contents

Instances

Synopsis

data Endpoint = Endpoint {
- _path :: [ String ]
- _method :: Method
}
showPath :: [ String ] -> String
defEndpoint :: Endpoint
data API = API {
- _apiIntros :: [ DocIntro ]
- _apiEndpoints :: HashMap Endpoint Action
}
emptyAPI :: API
data DocCapture = DocCapture {
- _capSymbol :: String
- _capDesc :: String
}
data DocQueryParam = DocQueryParam {
- _paramName :: String
- _paramValues :: [ String ]
- _paramDesc :: String
- _paramKind :: ParamKind
}
data DocFragment = DocFragment {
- _fragSymbol :: String
- _fragDesc :: String
}
combineFragment :: Maybe DocFragment -> Maybe DocFragment -> Maybe DocFragment
data DocIntro = DocIntro {
- _introTitle :: String
- _introBody :: [ String ]
}
data DocAuthentication = DocAuthentication {
- _authIntro :: String
- _authDataRequired :: String
}
data DocNote = DocNote {
- _noteTitle :: String
- _noteBody :: [ String ]
}
newtype ExtraInfo api = ExtraInfo ( HashMap Endpoint Action )
data DocOptions = DocOptions {
- _maxSamples :: Int
}
defaultDocOptions :: DocOptions
data ParamKind
- = Normal
- | List
- | Flag
data Response = Response {
- _respStatus :: Int
- _respTypes :: [ MediaType ]
- _respBody :: [( Text , MediaType , ByteString )]
- _respHeaders :: [ Header ]
}
combineResponse :: Response -> Response -> Response
defResponse :: Response
data Action = Action {
- _authInfo :: [ DocAuthentication ]
- _captures :: [ DocCapture ]
- _headers :: [ Header ]
- _params :: [ DocQueryParam ]
- _fragment :: Maybe DocFragment
- _notes :: [ DocNote ]
- _mxParams :: [( String , [ DocQueryParam ])]
- _rqtypes :: [ MediaType ]
- _rqbody :: [( Text , MediaType , ByteString )]
- _response :: Response
}
combineAction :: Action -> Action -> Action
defAction :: Action
single :: Endpoint -> Action -> API
data ShowContentTypes
- = AllContentTypes
- | FirstContentType
data RenderingOptions = RenderingOptions {
- _requestExamples :: ! ShowContentTypes
- _responseExamples :: ! ShowContentTypes
- _notesHeading :: !( Maybe String )
- _renderCurlBasePath :: !( Maybe String )
}
defRenderingOptions :: RenderingOptions
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
docsWithOptions :: HasDocs api => Proxy api -> DocOptions -> API
extraInfo :: ( IsIn endpoint api, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo api
docsWith :: HasDocs api => DocOptions -> [ DocIntro ] -> ExtraInfo api -> Proxy api -> API
docsWithIntros :: HasDocs api => [ DocIntro ] -> Proxy api -> API
class HasDocs api where
- docsFor :: Proxy api -> ( Endpoint , Action ) -> DocOptions -> API
class ToSample a where
- toSamples :: Proxy a -> [( Text , a)]
toSample :: forall a. ToSample a => Proxy a -> Maybe a
noSamples :: [( Text , a)]
singleSample :: a -> [( Text , a)]
samples :: [a] -> [( Text , a)]
defaultSamples :: forall a. ( Generic a, GToSample ( Rep a)) => Proxy a -> [( Text , a)]
class GToSample t where
- gtoSamples :: proxy t -> [( Text , t x)]
class AllHeaderSamples ls where
- allHeaderToSample :: Proxy ls -> [ Header ]
sampleByteString :: forall ct cts a. ( ToSample a, AllMimeRender (ct ': cts) a) => Proxy (ct ': cts) -> Proxy a -> [( MediaType , ByteString )]
sampleByteStrings :: forall ct cts a. ( ToSample a, AllMimeRender (ct ': cts) a) => Proxy (ct ': cts) -> Proxy a -> [( Text , MediaType , ByteString )]
class ToParam t where
- toParam :: Proxy t -> DocQueryParam
class ToCapture c where
- toCapture :: Proxy c -> DocCapture
class ToAuthInfo a where
- toAuthInfo :: Proxy a -> DocAuthentication
class ToFragment t where
- toFragment :: Proxy t -> DocFragment
markdown :: API -> String
markdownWith :: RenderingOptions -> API -> String

Documentation

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

Constructors

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

Instances

Instances details

Eq Endpoint Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: Endpoint -> Endpoint -> Bool Source # (/=) :: Endpoint -> Endpoint -> Bool Source #
Ord Endpoint Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: Endpoint -> Endpoint -> Ordering Source # (<) :: Endpoint -> Endpoint -> Bool Source # (<=) :: Endpoint -> Endpoint -> Bool Source # (>) :: Endpoint -> Endpoint -> Bool Source # (>=) :: Endpoint -> Endpoint -> Bool Source # max :: Endpoint -> Endpoint -> Endpoint Source # min :: Endpoint -> Endpoint -> Endpoint Source #
Show Endpoint Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> Endpoint -> ShowS Source # show :: Endpoint -> String Source # showList :: [ Endpoint ] -> ShowS Source #
Generic Endpoint Source #
Instance details Defined in Servant.Docs.Internal Associated Types type Rep Endpoint :: Type -> Type Source # Methods from :: Endpoint -> Rep Endpoint x Source # to :: Rep Endpoint x -> Endpoint Source #
Hashable Endpoint Source #
Instance details Defined in Servant.Docs.Internal Methods hashWithSalt :: Int -> Endpoint -> Int Source # hash :: Endpoint -> Int Source #
type Rep Endpoint Source #
Instance details Defined in Servant.Docs.Internal type Rep Endpoint = D1 (' MetaData "Endpoint" "Servant.Docs.Internal" "servant-docs-0.12-AKdA0B8Q8ZBCdDmf9jvuwk" ' 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 Source #

Render a path as a / -delimited string

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

Constructors

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

Instances

Instances details

Eq API Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: API -> API -> Bool Source # (/=) :: API -> API -> Bool Source #
Show API Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> API -> ShowS Source # show :: API -> String Source # showList :: [ API ] -> ShowS Source #
Semigroup API Source #
Instance details Defined in Servant.Docs.Internal Methods (<>) :: API -> API -> API Source # sconcat :: NonEmpty API -> API Source # stimes :: Integral b => b -> API -> API Source #
Monoid API Source #
Instance details Defined in Servant.Docs.Internal Methods mempty :: API Source # mappend :: API -> API -> API Source # mconcat :: [ API ] -> API Source #

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

Instances details

Eq DocCapture Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocCapture -> DocCapture -> Bool Source # (/=) :: DocCapture -> DocCapture -> Bool Source #
Ord DocCapture Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocCapture -> DocCapture -> Ordering Source # (<) :: DocCapture -> DocCapture -> Bool Source # (<=) :: DocCapture -> DocCapture -> Bool Source # (>) :: DocCapture -> DocCapture -> Bool Source # (>=) :: DocCapture -> DocCapture -> Bool Source # max :: DocCapture -> DocCapture -> DocCapture Source # min :: DocCapture -> DocCapture -> DocCapture Source #
Show DocCapture Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocCapture -> ShowS Source # show :: DocCapture -> String Source # showList :: [ DocCapture ] -> ShowS Source #

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

Constructors

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

Instances

Instances details

Eq DocQueryParam Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocQueryParam -> DocQueryParam -> Bool Source # (/=) :: DocQueryParam -> DocQueryParam -> Bool Source #
Ord DocQueryParam Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocQueryParam -> DocQueryParam -> Ordering Source # (<) :: DocQueryParam -> DocQueryParam -> Bool Source # (<=) :: DocQueryParam -> DocQueryParam -> Bool Source # (>) :: DocQueryParam -> DocQueryParam -> Bool Source # (>=) :: DocQueryParam -> DocQueryParam -> Bool Source # max :: DocQueryParam -> DocQueryParam -> DocQueryParam Source # min :: DocQueryParam -> DocQueryParam -> DocQueryParam Source #
Show DocQueryParam Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocQueryParam -> ShowS Source # show :: DocQueryParam -> String Source # showList :: [ DocQueryParam ] -> ShowS Source #

data DocFragment Source #

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

Instances details

Eq DocFragment Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocFragment -> DocFragment -> Bool Source # (/=) :: DocFragment -> DocFragment -> Bool Source #
Ord DocFragment Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocFragment -> DocFragment -> Ordering Source # (<) :: DocFragment -> DocFragment -> Bool Source # (<=) :: DocFragment -> DocFragment -> Bool Source # (>) :: DocFragment -> DocFragment -> Bool Source # (>=) :: DocFragment -> DocFragment -> Bool Source # max :: DocFragment -> DocFragment -> DocFragment Source # min :: DocFragment -> DocFragment -> DocFragment Source #
Show DocFragment Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocFragment -> ShowS Source # show :: DocFragment -> String Source # showList :: [ DocFragment ] -> ShowS Source #

combineFragment :: Maybe DocFragment -> Maybe DocFragment -> Maybe DocFragment Source #

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

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

Instances details

Eq DocIntro Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocIntro -> DocIntro -> Bool Source # (/=) :: DocIntro -> DocIntro -> Bool Source #
Ord DocIntro Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocIntro -> DocIntro -> Ordering Source # (<) :: DocIntro -> DocIntro -> Bool Source # (<=) :: DocIntro -> DocIntro -> Bool Source # (>) :: DocIntro -> DocIntro -> Bool Source # (>=) :: DocIntro -> DocIntro -> Bool Source # max :: DocIntro -> DocIntro -> DocIntro Source # min :: DocIntro -> DocIntro -> DocIntro Source #
Show DocIntro Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocIntro -> ShowS Source # show :: DocIntro -> String Source # showList :: [ DocIntro ] -> ShowS Source #

data DocAuthentication Source #

A type to represent Authentication information about an endpoint.

Constructors

DocAuthentication
Fields _authIntro :: String _authDataRequired :: String

Instances

Instances details

Eq DocAuthentication Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocAuthentication -> DocAuthentication -> Bool Source # (/=) :: DocAuthentication -> DocAuthentication -> Bool Source #
Ord DocAuthentication Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocAuthentication -> DocAuthentication -> Ordering Source # (<) :: DocAuthentication -> DocAuthentication -> Bool Source # (<=) :: DocAuthentication -> DocAuthentication -> Bool Source # (>) :: DocAuthentication -> DocAuthentication -> Bool Source # (>=) :: DocAuthentication -> DocAuthentication -> Bool Source # max :: DocAuthentication -> DocAuthentication -> DocAuthentication Source # min :: DocAuthentication -> DocAuthentication -> DocAuthentication Source #
Show DocAuthentication Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocAuthentication -> ShowS Source # show :: DocAuthentication -> String Source # showList :: [ DocAuthentication ] -> ShowS Source #

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

Instances details

Eq DocNote Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: DocNote -> DocNote -> Bool Source # (/=) :: DocNote -> DocNote -> Bool Source #
Ord DocNote Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: DocNote -> DocNote -> Ordering Source # (<) :: DocNote -> DocNote -> Bool Source # (<=) :: DocNote -> DocNote -> Bool Source # (>) :: DocNote -> DocNote -> Bool Source # (>=) :: DocNote -> DocNote -> Bool Source # max :: DocNote -> DocNote -> DocNote Source # min :: DocNote -> DocNote -> DocNote Source #
Show DocNote Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocNote -> ShowS Source # show :: DocNote -> String Source # showList :: [ DocNote ] -> ShowS Source #

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.

Constructors

ExtraInfo ( HashMap Endpoint Action )

Instances

Instances details

Semigroup ( ExtraInfo a) Source #
Instance details Defined in Servant.Docs.Internal Methods (<>) :: ExtraInfo a -> ExtraInfo a -> ExtraInfo a Source # sconcat :: NonEmpty ( ExtraInfo a) -> ExtraInfo a Source # stimes :: Integral b => b -> ExtraInfo a -> ExtraInfo a Source #
Monoid ( ExtraInfo a) Source #
Instance details Defined in Servant.Docs.Internal Methods mempty :: ExtraInfo a Source # mappend :: ExtraInfo a -> ExtraInfo a -> ExtraInfo a Source # mconcat :: [ ExtraInfo a] -> ExtraInfo a Source #

data DocOptions Source #

Documentation options.

Constructors

DocOptions
Fields _maxSamples :: Int Maximum samples allowed.

Instances

Instances details

Show DocOptions Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocOptions -> ShowS Source # show :: DocOptions -> String Source # showList :: [ DocOptions ] -> ShowS Source #

defaultDocOptions :: DocOptions Source #

Default documentation options.

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

Eq ParamKind Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: ParamKind -> ParamKind -> Bool Source # (/=) :: ParamKind -> ParamKind -> Bool Source #
Ord ParamKind Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: ParamKind -> ParamKind -> Ordering Source # (<) :: ParamKind -> ParamKind -> Bool Source # (<=) :: ParamKind -> ParamKind -> Bool Source # (>) :: ParamKind -> ParamKind -> Bool Source # (>=) :: ParamKind -> ParamKind -> Bool Source # max :: ParamKind -> ParamKind -> ParamKind Source # min :: ParamKind -> ParamKind -> ParamKind Source #
Show ParamKind Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> ParamKind -> ShowS Source # show :: ParamKind -> String Source # showList :: [ ParamKind ] -> ShowS Source #

data Response Source #

A type to represent an HTTP response. Has an Int status, a list of possible MediaType s, 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

Instances details

Eq Response Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: Response -> Response -> Bool Source # (/=) :: Response -> Response -> Bool Source #
Ord Response Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: Response -> Response -> Ordering Source # (<) :: Response -> Response -> Bool Source # (<=) :: Response -> Response -> Bool Source # (>) :: Response -> Response -> Bool Source # (>=) :: Response -> Response -> Bool Source # max :: Response -> Response -> Response Source # min :: Response -> Response -> Response Source #
Show Response Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> Response -> ShowS Source # show :: Response -> String Source # showList :: [ Response ] -> ShowS Source #

combineResponse :: Response -> Response -> Response Source #

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

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

Instances details

Eq Action Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: Action -> Action -> Bool Source # (/=) :: Action -> Action -> Bool Source #
Ord Action Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: Action -> Action -> Ordering Source # (<) :: Action -> Action -> Bool Source # (<=) :: Action -> Action -> Bool Source # (>) :: Action -> Action -> Bool Source # (>=) :: Action -> Action -> Bool Source # max :: Action -> Action -> Action Source # min :: Action -> Action -> Action Source #
Show Action Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> Action -> ShowS Source # show :: Action -> String Source # showList :: [ Action ] -> ShowS Source #

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 from the very left.

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

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 Methods minBound :: ShowContentTypes Source # maxBound :: ShowContentTypes Source #
Enum ShowContentTypes Source #
Instance details Defined in Servant.Docs.Internal Methods succ :: ShowContentTypes -> ShowContentTypes Source # pred :: ShowContentTypes -> ShowContentTypes Source # toEnum :: Int -> ShowContentTypes Source # fromEnum :: ShowContentTypes -> Int Source # enumFrom :: ShowContentTypes -> [ ShowContentTypes ] Source # enumFromThen :: ShowContentTypes -> ShowContentTypes -> [ ShowContentTypes ] Source # enumFromTo :: ShowContentTypes -> ShowContentTypes -> [ ShowContentTypes ] Source # enumFromThenTo :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes -> [ ShowContentTypes ] Source #
Eq ShowContentTypes Source #
Instance details Defined in Servant.Docs.Internal Methods (==) :: ShowContentTypes -> ShowContentTypes -> Bool Source # (/=) :: ShowContentTypes -> ShowContentTypes -> Bool Source #
Ord ShowContentTypes Source #
Instance details Defined in Servant.Docs.Internal Methods compare :: ShowContentTypes -> ShowContentTypes -> Ordering Source # (<) :: ShowContentTypes -> ShowContentTypes -> Bool Source # (<=) :: ShowContentTypes -> ShowContentTypes -> Bool Source # (>) :: ShowContentTypes -> ShowContentTypes -> Bool Source # (>=) :: ShowContentTypes -> ShowContentTypes -> Bool Source # max :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes Source # min :: ShowContentTypes -> ShowContentTypes -> ShowContentTypes Source #
Read ShowContentTypes Source #
Instance details Defined in Servant.Docs.Internal Methods readsPrec :: Int -> ReadS ShowContentTypes Source # readList :: ReadS [ ShowContentTypes ] Source # readPrec :: ReadPrec ShowContentTypes Source # readListPrec :: ReadPrec [ ShowContentTypes ] Source #
Show ShowContentTypes Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> ShowContentTypes -> ShowS Source # show :: ShowContentTypes -> String Source # showList :: [ ShowContentTypes ] -> ShowS Source #

data RenderingOptions Source #

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

Instances details

Show RenderingOptions Source #
Instance details Defined in Servant.Docs.Internal Methods showsPrec :: Int -> RenderingOptions -> ShowS Source # show :: RenderingOptions -> String Source # showList :: [ RenderingOptions ] -> ShowS Source #

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

authIntro :: Lens' DocAuthentication String Source #

authDataRequired :: Lens' DocAuthentication String Source #

maxSamples :: Iso' DocOptions Int Source #

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 #

fragSymbol :: Lens' DocFragment String Source #

fragDesc :: Lens' DocFragment 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 [( Text , 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 [ Header ] Source #

fragment :: Lens' Action ( Maybe DocFragment ) Source #

captures :: Lens' Action [ DocCapture ] Source #

authInfo :: Lens' Action [ DocAuthentication ] Source #

responseExamples :: Lens' RenderingOptions ShowContentTypes Source #

requestExamples :: Lens' RenderingOptions ShowContentTypes Source #

renderCurlBasePath :: Lens' RenderingOptions ( Maybe String ) Source #

notesHeading :: Lens' RenderingOptions ( Maybe String ) 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

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

Generate the docs for a given API that implements HasDocs .

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

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 with any number of introduction(s)

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 Raw Source #
Instance details Defined in Servant.Docs.Internal Methods docsFor :: Proxy Raw -> ( Endpoint , Action ) -> DocOptions -> API Source #
HasDocs EmptyAPI Source #	The generated docs for `EmptyAPI` are empty.
Instance details Defined in Servant.Docs.Internal Methods docsFor :: Proxy EmptyAPI -> ( Endpoint , Action ) -> DocOptions -> API Source #
ReflectMethod method => HasDocs ( NoContentVerb method :: Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods docsFor :: Proxy ( NoContentVerb method) -> ( Endpoint , Action ) -> DocOptions -> API Source #
( 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 #
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 #
HasDocs api => HasDocs ( HttpVersion :> api :: Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods docsFor :: Proxy ( HttpVersion :> 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 #
( 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 => HasDocs ( RemoteHost :> api :: Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods docsFor :: Proxy ( RemoteHost :> 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 #
( 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 #
( 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 Methods docsFor :: Proxy ( IsSecure :> 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 #
( 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 #
( 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 #
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 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 #
( 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 #
( 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 #
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 #
( 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 #
( 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 #
( 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 #

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 Text ) 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 Bool Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy Bool -> [( Text , Bool )] Source #
ToSample Ordering Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy Ordering -> [( Text , Ordering )] Source #
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 NoContent Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy NoContent -> [( Text , NoContent )] Source #
ToSample a => ToSample [a] Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy [a] -> [( Text , [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 ( 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 ( Sum a) Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy ( Sum a) -> [( Text , Sum 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 ( NonEmpty a) Source #
Instance details Defined in Servant.Docs.Internal Methods toSamples :: Proxy ( NonEmpty a) -> [( Text , NonEmpty 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 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 ( 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 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.

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

Default sample Generic-based inputs/outputs.

class GToSample t where Source #

ToSample for Generics.

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

Methods

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

Instances

Instances details

GToSample ( V1 :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy V1 -> [( Text , V1 x)] Source #
GToSample ( U1 :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy U1 -> [( Text , U1 x)] Source #
( GToSample p, GToSample q) => GToSample (p :+: q :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy (p :+: q) -> [( Text , (p :+: q) x)] Source #
( GToSample p, GToSample q) => GToSample (p :*: q :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy (p :: q) -> [( Text , (p :: q) x)] Source #
ToSample a => GToSample ( K1 i a :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy ( K1 i a) -> [( Text , K1 i a x)] Source #
GToSample f => GToSample ( M1 i a f :: k -> Type ) Source #
Instance details Defined in Servant.Docs.Internal Methods gtoSamples :: forall proxy (x :: k0). proxy ( M1 i a f) -> [( Text , M1 i a f x)] Source #

class AllHeaderSamples ls where Source #

Methods

allHeaderToSample :: Proxy ls -> [ Header ] Source #

Instances

Instances details

AllHeaderSamples ('[] :: [k]) Source #
Instance details Defined in Servant.Docs.Internal Methods allHeaderToSample :: Proxy '[] -> [ Header ] Source #
( ToHttpApiData l, AllHeaderSamples ls, ToSample l, KnownSymbol h) => AllHeaderSamples ( Header h l ': ls :: [ Type ]) Source #
Instance details Defined in Servant.Docs.Internal Methods allHeaderToSample :: Proxy ( Header h l ': ls) -> [ Header0 ] Source #

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

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 #

class ToAuthInfo a where Source #

The class that helps us get documentation for authenticated endpoints

Methods

toAuthInfo :: Proxy a -> DocAuthentication Source #

class ToFragment t where Source #

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 Source #

markdown :: API -> String Source #

Generate documentation in Markdown format for the given API .

This is equivalent to markdownWith defRenderingOptions .

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

Instances

>>> :set -XOverloadedStrings