| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
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 ::HasDocsapi =>Proxyapi ->API
Alternatively, if you wish to add one or more introductions to your
documentation, use docsWithIntros:
docsWithIntros::HasDocsapi => [DocIntro] ->Proxyapi ->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
- class HasDocs api where
- docs :: HasDocs api => Proxy api -> API
- pretty :: Proxy api -> Proxy (Pretty api)
- markdown :: API -> String
- markdownWith :: RenderingOptions -> API -> String
- data RenderingOptions = RenderingOptions {}
- defRenderingOptions :: RenderingOptions
- requestExamples :: Lens' RenderingOptions ShowContentTypes
- responseExamples :: Lens' RenderingOptions ShowContentTypes
- data ShowContentTypes
- notesHeading :: Lens' RenderingOptions (Maybe String)
- docsWith :: HasDocs api => DocOptions -> [DocIntro] -> ExtraInfo api -> Proxy api -> API
- docsWithIntros :: HasDocs api => [DocIntro] -> Proxy api -> API
- docsWithOptions :: HasDocs api => Proxy api -> DocOptions -> API
- newtype ExtraInfo api = ExtraInfo (HashMap Endpoint Action)
- extraInfo :: (IsIn endpoint api, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo api
- data DocOptions = DocOptions {
- _maxSamples :: Int
- defaultDocOptions :: DocOptions
- maxSamples :: Iso' DocOptions Int
- class ToSample a where
- toSample :: forall a. ToSample a => Proxy a -> Maybe a
- noSamples :: [(Text, a)]
- singleSample :: a -> [(Text, a)]
- samples :: [a] -> [(Text, a)]
- 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
- data Endpoint
- path :: Lens' Endpoint [String]
- method :: Lens' Endpoint Method
- defEndpoint :: Endpoint
- data API
- apiIntros :: Lens' API [DocIntro]
- apiEndpoints :: Lens' API (HashMap Endpoint Action)
- emptyAPI :: API
- data DocAuthentication = DocAuthentication {}
- authIntro :: Lens' DocAuthentication String
- authDataRequired :: Lens' DocAuthentication String
- data DocCapture = DocCapture {
- _capSymbol :: String
- _capDesc :: String
- capSymbol :: Lens' DocCapture String
- capDesc :: Lens' DocCapture String
- data DocQueryParam = DocQueryParam {
- _paramName :: String
- _paramValues :: [String]
- _paramDesc :: String
- _paramKind :: ParamKind
- data ParamKind
- paramName :: Lens' DocQueryParam String
- paramValues :: Lens' DocQueryParam [String]
- paramDesc :: Lens' DocQueryParam String
- paramKind :: Lens' DocQueryParam ParamKind
- data DocNote = DocNote {
- _noteTitle :: String
- _noteBody :: [String]
- noteTitle :: Lens' DocNote String
- noteBody :: Lens' DocNote [String]
- data DocIntro = DocIntro {
- _introTitle :: String
- _introBody :: [String]
- introTitle :: Lens' DocIntro String
- introBody :: Lens' DocIntro [String]
- data Response = Response {
- _respStatus :: Int
- _respTypes :: [MediaType]
- _respBody :: [(Text, MediaType, ByteString)]
- _respHeaders :: [Header]
- respStatus :: Lens' Response Int
- respTypes :: Lens' Response [MediaType]
- respBody :: Lens' Response [(Text, MediaType, ByteString)]
- defResponse :: Response
- data Action
- authInfo :: Lens' Action [DocAuthentication]
- captures :: Lens' Action [DocCapture]
- headers :: Lens' Action [Header]
- notes :: Lens' Action [DocNote]
- params :: Lens' Action [DocQueryParam]
- rqtypes :: Lens' Action [MediaType]
- rqbody :: Lens' Action [(Text, MediaType, ByteString)]
- response :: Lens' Action Response
- defAction :: Action
- single :: Endpoint -> Action -> API
HasDocs class and key functions
class HasDocs api where Source #
The class that abstracts away the impact of API combinators on documentation generation.
Instances
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
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
| Show RenderingOptions Source # | |
Defined in Servant.Docs.Internal Methods showsPrec :: Int -> RenderingOptions -> ShowS # show :: RenderingOptions -> String # showList :: [RenderingOptions] -> ShowS # | |
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
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.
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
| Show DocOptions Source # | |
Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocOptions -> ShowS # show :: DocOptions -> String # showList :: [DocOptions] -> ShowS # | |
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
Instances
toSample :: forall a. ToSample a => Proxy a -> Maybe a Source #
Sample input or output (if there is at least one).
singleSample :: a -> [(Text, a)] Source #
Single sample without description.
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 #
ADTs to represent an API
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
| Generic Endpoint Source # | |
| Show Endpoint Source # | |
| Eq Endpoint Source # | |
| Ord Endpoint Source # | |
Defined in Servant.Docs.Internal | |
| Hashable Endpoint Source # | |
Defined in Servant.Docs.Internal | |
| type Rep Endpoint Source # | |
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
Our API documentation type, a product of top-level information and a good
old hashmap from Endpoint to Action
data DocAuthentication Source #
A type to represent Authentication information about an endpoint.
Constructors
| DocAuthentication | |
Fields | |
Instances
| Show DocAuthentication Source # | |
Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocAuthentication -> ShowS # show :: DocAuthentication -> String # showList :: [DocAuthentication] -> ShowS # | |
| Eq DocAuthentication Source # | |
Defined in Servant.Docs.Internal Methods (==) :: DocAuthentication -> DocAuthentication -> Bool # (/=) :: DocAuthentication -> DocAuthentication -> Bool # | |
| Ord DocAuthentication Source # | |
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 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
| |
Instances
| Show DocCapture Source # | |
Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocCapture -> ShowS # show :: DocCapture -> String # showList :: [DocCapture] -> ShowS # | |
| Eq DocCapture Source # | |
Defined in Servant.Docs.Internal | |
| Ord DocCapture Source # | |
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 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
| |
Instances
| Show DocQueryParam Source # | |
Defined in Servant.Docs.Internal Methods showsPrec :: Int -> DocQueryParam -> ShowS # show :: DocQueryParam -> String # showList :: [DocQueryParam] -> ShowS # | |
| Eq DocQueryParam Source # | |
Defined in Servant.Docs.Internal Methods (==) :: DocQueryParam -> DocQueryParam -> Bool # (/=) :: DocQueryParam -> DocQueryParam -> Bool # | |
| Ord DocQueryParam Source # | |
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 # | |
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
Instances
| Show ParamKind Source # | |
| Eq ParamKind Source # | |
| Ord ParamKind 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
| |
An introductory paragraph for your documentation. You can pass these to
docsWithIntros.
Constructors
| DocIntro | |
Fields
| |
A type to represent an HTTP response. Has an Int status, a list of
possible MediaTypes, and a list of example ByteString response bodies.
Tweak defResponse using the respStatus, respTypes and respBody
lenses if you want.
If you want to respond with a non-empty response body, you'll most likely
want to write a ToSample instance for the type that'll be represented
as encoded data in the response.
Can be tweaked with four lenses.
>>>defResponseResponse {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}
>>>defResponse & respStatus .~ 204 & respBody .~ [("If everything goes well", "application/json", "{ \"status\": \"ok\" }")]Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well",application/json,"{ \"status\": \"ok\" }")], _respHeaders = []}
Constructors
| Response | |
Fields
| |
defResponse :: Response Source #
Default response: status code 200, no response body.
Can be tweaked with four lenses.
>>>defResponseResponse {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}
>>>defResponse & respStatus .~ 204Response {_respStatus = 204, _respTypes = [], _respBody = [], _respHeaders = []}
A datatype that represents everything that can happen at an endpoint, with its lenses:
- List of captures (
captures) - List of GET (or other
Method) parameters (params) - What the request body should look like, if any is requested (
rqbody) - What the response should be if everything goes well (
response)
You can tweak an Action (like the default defAction) with these lenses
to transform an action and add some information to it.
Default Action. Has no captures, no query params, expects
no request body (rqbody) and the typical response is defResponse.
Tweakable with lenses.
>>>defActionAction {_authInfo = [], _captures = [], _headers = [], _params = [], _fragment = Nothing, _notes = [], _mxParams = [], _rqtypes = [], _rqbody = [], _response = Response {_respStatus = 200, _respTypes = [], _respBody = [], _respHeaders = []}}
>>>defAction & response.respStatus .~ 201Action {_authInfo = [], _captures = [], _headers = [], _params = [], _fragment = Nothing, _notes = [], _mxParams = [], _rqtypes = [], _rqbody = [], _response = Response {_respStatus = 201, _respTypes = [], _respBody = [], _respHeaders = []}}