Servant.Auth.Docs

Documentation

The purpose of this package is provide the instance for 'servant-auth' combinators needed for 'servant-docs' documentation generation.

>>> type API = Auth '[JWT, Cookie, BasicAuth] Int :> Get '[JSON] Int
>>> putStr $ markdown $ docs (Proxy :: Proxy API)
## GET /
...
#### Authentication
...
This part of the API is protected by the following authentication mechanisms:
...
 * JSON Web Tokens ([JWTs](https://en.wikipedia.org/wiki/JSON_Web_Token))
 * [Cookies](https://en.wikipedia.org/wiki/HTTP_cookie)
 * [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
...
...
Clients must supply the following data
...
One of the following:
...
 * A JWT Token signed with this server's key
 * Cookies automatically set by browsers, plus a header
 * Cookies automatically set by browsers, plus a header
...

Re-export

data JWT :: *

A JSON Web Token (JWT) in the the Authorization header:

Authorization: Bearer token

Note that while the token is signed, it is not encrypted. Therefore do not keep in it any information you would not like the client to know.

JWTs are described in IETF's RFC 7519

data BasicAuth :: *

Basic Auth.

data Cookie :: *

A cookie. The content cookie itself is a JWT. Another cookie is also used, the contents of which are expected to be send back to the server in a header, for CSRF protection.

data Auth auths val :: [*] -> * -> *

Auth [auth1, auth2] val :> api represents an API protected *either* by auth1 or auth2

Orphan instances

(AllDocs auths, HasDocs * api) => HasDocs * ((:>) * * (Auth auths r) api)

Methods

docsFor :: Proxy ((* :> *) (Auth auths r) api) api -> (Endpoint, Action) -> DocOptions -> API