| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Servant.Docs.Internal
Contents
- data Endpoint = Endpoint {}
- showPath :: [String] -> String
- defEndpoint :: Endpoint
- data API = API {}
- emptyAPI :: API
- data DocCapture = DocCapture {
- _capSymbol :: String
- _capDesc :: String
- data DocQueryParam = DocQueryParam {
- _paramName :: String
- _paramValues :: [String]
- _paramDesc :: String
- _paramKind :: ParamKind
- data DocIntro = DocIntro {
- _introTitle :: String
- _introBody :: [String]
- data DocAuthentication = DocAuthentication {}
- data DocNote = DocNote {
- _noteTitle :: String
- _noteBody :: [String]
- newtype ExtraInfo api = ExtraInfo (HashMap Endpoint Action)
- data DocOptions = DocOptions {
- _maxSamples :: Int
- defaultDocOptions :: DocOptions
- data ParamKind
- data Response = Response {
- _respStatus :: Int
- _respTypes :: [MediaType]
- _respBody :: [(Text, MediaType, ByteString)]
- _respHeaders :: [Header]
- defResponse :: Response
- data Action = Action {
- _authInfo :: [DocAuthentication]
- _captures :: [DocCapture]
- _headers :: [Text]
- _params :: [DocQueryParam]
- _notes :: [DocNote]
- _mxParams :: [(String, [DocQueryParam])]
- _rqtypes :: [MediaType]
- _rqbody :: [(MediaType, ByteString)]
- _response :: Response
- combineAction :: Action -> Action -> Action
- defAction :: Action
- single :: Endpoint -> Action -> API
- 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
- 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 [(MediaType, ByteString)]
- response :: Lens' Action Response
- params :: Lens' Action [DocQueryParam]
- notes :: Lens' Action [DocNote]
- mxParams :: Lens' Action [(String, [DocQueryParam])]
- headers :: Lens' Action [Text]
- captures :: Lens' Action [DocCapture]
- authInfo :: Lens' Action [DocAuthentication]
- docs :: HasDocs api => Proxy api -> API
- docsWithOptions :: HasDocs api => Proxy api -> DocOptions -> API
- type family IsIn (endpoint :: *) (api :: *) :: Constraint where ...
- 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
- class ToSample a where
- 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
- class AllHeaderSamples ls where
- 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
- class ToCapture c where
- class ToAuthInfo a where
- markdown :: API -> String
Documentation
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.
λ>defEndpointGET / λ>defEndpoint&path<>~["foo"] GET /foo λ>defEndpoint&path<>~["foo"] &method.~methodPostPOST /foo
defEndpoint :: Endpoint Source #
An Endpoint whose path is `"/"` and whose method is GET
Here's how you can modify it:
λ>defEndpointGET / λ>defEndpoint&path<>~["foo"] GET /foo λ>defEndpoint&path<>~["foo"] &method.~methodPostPOST /foo
Our API documentation type, a product of top-level information and a good
old hashmap from Endpoint to Action
Constructors
| API | |
Fields
| |
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
data DocQueryParam Source #
A type to represent a GET 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
An introductory paragraph for your documentation. You can pass these to
docsWithIntros.
Constructors
| DocIntro | |
Fields
| |
data DocAuthentication Source #
A type to represent Authentication information about an endpoint.
Constructors
| DocAuthentication | |
Fields | |
Instances
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
| |
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.
data DocOptions Source #
Documentation options.
Constructors
| DocOptions | |
Fields
| |
Instances
defaultDocOptions :: DocOptions Source #
Default documentation options.
Type of GET 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
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 three lenses.
λ> defResponse
Response {_respStatus = 200, _respTypes = [], _respBody = []}
λ> defResponse & respStatus .~ 204 & respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]
Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}Constructors
| Response | |
Fields
| |
defResponse :: Response Source #
Default response: status code 200, no response body.
Can be tweaked with two lenses.
λ> defResponse
Response {_respStatus = 200, _respBody = Nothing}
λ> defResponse & respStatus .~ 204 & respBody .~ Just "[]"
Response {_respStatus = 204, _respBody = Just "[]"}A datatype that represents everything that can happen at an endpoint, with its lenses:
- List of captures (
captures) - List of GET 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
| |
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, body and content
types from the very left.
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.
type family IsIn (endpoint :: *) (api :: *) :: Constraint where ... Source #
Closed type family, check if endpoint is exactly within API.
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 <>~ ["unicorns"]
& notes <>~ [ DocNote "Title" ["This is some text"]
, DocNote "Second secton" ["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.
Minimal complete definition
Instances
| HasDocs * Raw Source # | |
| (HasDocs * a, HasDocs * b) => HasDocs * ((:<|>) a b) Source # | The generated docs for |
| HasDocs * api => HasDocs * (WithNamedContext name context api) Source # | |
| (ToAuthInfo * (BasicAuth realm usr), HasDocs k1 api) => HasDocs * ((:>) * k1 (BasicAuth realm usr) api) Source # | |
| HasDocs k1 api => HasDocs * ((:>) * k1 Vault api) Source # | |
| HasDocs k1 api => HasDocs * ((:>) * k1 HttpVersion api) Source # | |
| HasDocs k1 api => HasDocs * ((:>) * k1 IsSecure api) Source # | |
| HasDocs k1 api => HasDocs * ((:>) * k1 RemoteHost api) Source # | |
| (ToSample a, AllMimeRender ((:) * ct cts) a, HasDocs k1 api) => HasDocs * ((:>) * k1 (ReqBody * ((:) * ct cts) a) api) Source # | |
| (KnownSymbol sym, ToParam * (QueryFlag sym), HasDocs k1 api) => HasDocs * ((:>) * k1 (QueryFlag sym) api) Source # | |
| (KnownSymbol sym, ToParam * (QueryParams k sym a), HasDocs k1 api) => HasDocs * ((:>) * k1 (QueryParams k sym a) api) Source # | |
| (KnownSymbol sym, ToParam * (QueryParam k sym a), HasDocs k1 api) => HasDocs * ((:>) * k1 (QueryParam k sym a) api) Source # | |
| (KnownSymbol sym, HasDocs k1 api) => HasDocs * ((:>) * k1 (Header sym a) api) Source # | |
| (KnownSymbol sym, ToCapture * (CaptureAll k sym a), HasDocs k1 sublayout) => HasDocs * ((:>) * k1 (CaptureAll k sym a) sublayout) Source # |
|
| (KnownSymbol sym, ToCapture * (Capture k sym a), HasDocs k1 api) => HasDocs * ((:>) * k1 (Capture k sym a) api) Source # |
|
| (KnownSymbol path, HasDocs k1 api) => HasDocs * ((:>) Symbol k1 path api) Source # | |
| (ToSample a, AllMimeRender ((:) * ct cts) a, KnownNat status, ReflectMethod k1 method, AllHeaderSamples [*] ls, GetHeaders (HList ls)) => HasDocs * (Verb k1 * method status ((:) * ct cts) (Headers ls a)) Source # | |
| (ToSample a, AllMimeRender ((:) * ct cts) a, KnownNat status, ReflectMethod k1 method) => HasDocs * (Verb k1 * method status ((:) * ct cts) a) 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.
Methods
toSamples :: Proxy a -> [(Text, a)] Source #
toSamples :: (Generic a, GToSample (Rep a)) => Proxy a -> [(Text, a)] Source #
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.
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
The use of Omega
Minimal complete definition
Methods
gtoSamples :: proxy t -> Omega (Text, t x) Source #
class AllHeaderSamples ls where Source #
Minimal complete definition
Methods
allHeaderToSample :: Proxy ls -> [Header] Source #
Instances
| AllHeaderSamples [k] ([] k) Source # | |
| (ToHttpApiData l, AllHeaderSamples [*] ls, ToSample l, KnownSymbol h) => AllHeaderSamples [*] ((:) * (Header h l) ls) 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 parameters.
Example of an instance:
instance ToParam (QueryParam "capital" Bool) where
toParam _ =
DocQueryParam "capital"
["true", "false"]
"Get the greeting message in uppercase (true) or not (false). Default is false."Minimal complete definition
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"
Minimal complete definition
Methods
toCapture :: Proxy c -> DocCapture Source #
class ToAuthInfo a where Source #
The class that helps us get documentation for authenticated endpoints
Minimal complete definition
Methods
toAuthInfo :: Proxy a -> DocAuthentication Source #