Servant.Swagger.Internal

Documentation

class HasSwagger api where

Generate a Swagger specification for a servant API.

To generate Swagger specification, your data types need ToParamSchema and/or ToSchema instances.

ToParamSchema is used for Capture, QueryParam and Header. ToSchema is used for ReqBody and response data types.

You can easily derive those instances via Generic. For more information, refer to swagger2 documentation.

Example:

newtype Username = Username String deriving (Generic, ToText)

instance ToParamSchema Username

data User = User
  { username :: Username
  , fullname :: String
  } deriving (Generic)

instance ToJSON User
instance ToSchema User

type MyAPI = QueryParam "username" Username :> Get '[JSON] User

mySwagger :: Swagger
mySwagger = toSwagger (Proxy :: Proxy MyAPI)

Minimal complete definition

toSwagger

Methods

toSwagger :: Proxy api -> Swagger

Generate a Swagger specification for a servant API.

Instances

HasSwagger * Raw

Methods

toSwagger :: Proxy Raw api -> Swagger

HasSwagger * EmptyAPI

Methods

toSwagger :: Proxy EmptyAPI api -> Swagger

(HasSwagger * a, HasSwagger * b) => HasSwagger * ((:<|>) a b)

Methods

toSwagger :: Proxy (a :<|> b) api -> Swagger

HasSwagger * sub => HasSwagger * (WithNamedContext x c sub)

WithNamedContext combinator does not change our specification at all.

Methods

toSwagger :: Proxy (WithNamedContext x c sub) api -> Swagger

HasSwagger * sub => HasSwagger * ((:>) * HttpVersion sub)

HttpVersion combinator does not change our specification at all.

Methods

toSwagger :: Proxy ((* :> HttpVersion) sub) api -> Swagger

(ToSchema a, AllAccept [*] cs, HasSwagger * sub, KnownSymbol (FoldDescription mods)) => HasSwagger * ((:>) * (ReqBody' mods cs a) sub)

Methods

toSwagger :: Proxy ((* :> ReqBody' mods cs a) sub) api -> Swagger

HasSwagger * sub => HasSwagger * ((:>) * RemoteHost sub)

RemoteHost combinator does not change our specification at all.

Methods

toSwagger :: Proxy ((* :> RemoteHost) sub) api -> Swagger

(KnownSymbol sym, ToParamSchema a, HasSwagger * sub, SBoolI (FoldRequired mods), KnownSymbol (FoldDescription mods)) => HasSwagger * ((:>) * (QueryParam' mods sym a) sub)

Methods

toSwagger :: Proxy ((* :> QueryParam' mods sym a) sub) api -> Swagger

(KnownSymbol sym, ToParamSchema a, HasSwagger * sub) => HasSwagger * ((:>) * (QueryParams sym a) sub)

Methods

toSwagger :: Proxy ((* :> QueryParams sym a) sub) api -> Swagger

(KnownSymbol sym, HasSwagger * sub) => HasSwagger * ((:>) * (QueryFlag sym) sub)

Methods

toSwagger :: Proxy ((* :> QueryFlag sym) sub) api -> Swagger

(KnownSymbol sym, ToParamSchema a, HasSwagger * sub, SBoolI (FoldRequired mods), KnownSymbol (FoldDescription mods)) => HasSwagger * ((:>) * (Header' * mods sym a) sub)

Methods

toSwagger :: Proxy ((* :> Header' * mods sym a) sub) api -> Swagger

HasSwagger * sub => HasSwagger * ((:>) * IsSecure sub)

IsSecure combinator does not change our specification at all.

Methods

toSwagger :: Proxy ((* :> IsSecure) sub) api -> Swagger

(KnownSymbol desc, HasSwagger * api) => HasSwagger * ((:>) * (Summary desc) api)

Methods

toSwagger :: Proxy ((* :> Summary desc) api) api -> Swagger

(KnownSymbol desc, HasSwagger * api) => HasSwagger * ((:>) * (Description desc) api)

Methods

toSwagger :: Proxy ((* :> Description desc) api) api -> Swagger

(KnownSymbol sym, ToParamSchema a, HasSwagger * sub, KnownSymbol (FoldDescription mods)) => HasSwagger * ((:>) * (Capture' mods sym a) sub)

Methods

toSwagger :: Proxy ((* :> Capture' mods sym a) sub) api -> Swagger

(KnownSymbol sym, ToParamSchema a, HasSwagger * sub) => HasSwagger * ((:>) * (CaptureAll sym a) sub)

Swagger Spec doesn't have a notion of CaptureAll, this instance is the best effort.

Methods

toSwagger :: Proxy ((* :> CaptureAll sym a) sub) api -> Swagger

HasSwagger * sub => HasSwagger * ((:>) * Vault sub)

Vault combinator does not change our specification at all.

Methods

toSwagger :: Proxy ((* :> Vault) sub) api -> Swagger

(KnownSymbol sym, HasSwagger * sub) => HasSwagger * ((:>) Symbol sym sub)

Methods

toSwagger :: Proxy ((Symbol :> sym) sub) api -> Swagger

(AllAccept [*] cs, KnownNat status, SwaggerMethod k1 method) => HasSwagger * (Verb k1 method status cs NoContent)

Methods

toSwagger :: Proxy (Verb k1 method status cs NoContent) api -> Swagger

(ToSchema a, AllAccept [*] cs, KnownNat status, SwaggerMethod k1 method) => HasSwagger * (Verb k1 method status cs a)

Methods

toSwagger :: Proxy (Verb k1 method status cs a) api -> Swagger

(AllAccept [*] cs, AllToResponseHeader [*] hs, KnownNat status, SwaggerMethod k1 method) => HasSwagger * (Verb k1 method status cs (Headers hs NoContent))

Methods

toSwagger :: Proxy (Verb k1 method status cs (Headers hs NoContent)) api -> Swagger

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs, KnownNat status, SwaggerMethod k1 method) => HasSwagger * (Verb k1 method status cs (Headers hs a))

Methods

toSwagger :: Proxy (Verb k1 method status cs (Headers hs a)) api -> Swagger

subOperations

Arguments

:: (IsSubAPI sub api, HasSwagger sub)

=> Proxy sub

Part of a servant API.

-> Proxy api

The whole servant API.

-> Traversal' Swagger Operation

All operations of sub API. This is similar to operationsOf but ensures that operations indeed belong to the API at compile time.

mkEndpoint

Arguments

:: (ToSchema a, AllAccept cs, AllToResponseHeader hs, SwaggerMethod method, KnownNat status)

=> FilePath

Endpoint path.

-> proxy (Verb method status cs (Headers hs a))

Method, content-types, headers and response.

-> Swagger

Make a singleton Swagger spec (with only one endpoint). For endpoints with no content see mkEndpointNoContent.

mkEndpointNoContent

Arguments

:: (AllAccept cs, AllToResponseHeader hs, SwaggerMethod method, KnownNat status)

=> FilePath

Endpoint path.

-> proxy (Verb method status cs (Headers hs nocontent))

Method, content-types, headers and response.

-> Swagger

Make a singletone Swagger spec (with only one endpoint) and with no content schema.

mkEndpointWithSchemaRef :: forall cs hs proxy method status a. (AllAccept cs, AllToResponseHeader hs, SwaggerMethod method, KnownNat status) => Maybe (Referenced Schema) -> FilePath -> proxy (Verb method status cs (Headers hs a)) -> Swagger

Like mkEndpoint but with explicit schema reference. Unlike mkEndpoint this function does not update definitions.

addParam :: Param -> Swagger -> Swagger

Add parameter to every operation in the spec.

addConsumes :: [MediaType] -> Swagger -> Swagger

Add accepted content types to every operation in the spec.

markdownCode :: Text -> Text

Format given text as inline code in Markdown.

addDefaultResponse404 :: ParamName -> Swagger -> Swagger

addDefaultResponse400 :: ParamName -> Swagger -> Swagger

class SwaggerMethod method where

Methods, available for Swagger.

Minimal complete definition

swaggerMethod

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

Instances

SwaggerMethod StdMethod PATCH

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod OPTIONS

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod DELETE

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod PUT

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod HEAD

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod POST

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

SwaggerMethod StdMethod GET

Methods

swaggerMethod :: proxy method -> Lens' PathItem (Maybe Operation)

class AllAccept cs where

Minimal complete definition

allContentType

Methods

allContentType :: Proxy cs -> [MediaType]

Instances

AllAccept [k] ([] k)

Methods

allContentType :: Proxy [k] cs -> [MediaType]

(Accept a c, AllAccept [a] cs) => AllAccept [a] ((:) a c cs)

Methods

allContentType :: Proxy ((a ': c) cs) cs -> [MediaType]

class ToResponseHeader h where

Minimal complete definition

toResponseHeader

Methods

toResponseHeader :: Proxy h -> (HeaderName, Header)

Instances

(KnownSymbol sym, ToParamSchema a) => ToResponseHeader * (Header * sym a)

Methods

toResponseHeader :: Proxy (Header * sym a) h -> (HeaderName, Header)

class AllToResponseHeader hs where

Minimal complete definition

toAllResponseHeaders

Methods

toAllResponseHeaders :: Proxy hs -> InsOrdHashMap HeaderName Header

Instances

AllToResponseHeader [k] ([] k)

Methods

toAllResponseHeaders :: Proxy [k] hs -> InsOrdHashMap HeaderName Header

AllToResponseHeader [*] hs => AllToResponseHeader * (HList hs)

Methods

toAllResponseHeaders :: Proxy (HList hs) hs -> InsOrdHashMap HeaderName Header

(ToResponseHeader a h, AllToResponseHeader [a] hs) => AllToResponseHeader [a] ((:) a h hs)

Methods

toAllResponseHeaders :: Proxy ((a ': h) hs) hs -> InsOrdHashMap HeaderName Header