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

(ToSchema a, AllAccept [*] cs, HasSwagger k sub) => HasSwagger * ((:>) k * (ReqBody * cs a) sub)

Methods

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

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

Methods

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

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

Methods

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

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

Methods

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

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

Methods

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

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

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

Methods

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

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

Methods

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

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

Methods

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

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

HttpVersion combinator does not change our specification at all.

Methods

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

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

RemoteHost combinator does not change our specification at all.

Methods

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

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

IsSecure combinator does not change our specification at all.

Methods

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

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

Vault combinator does not change our specification at all.

Methods

toSwagger :: Proxy ((k :> *) Vault sub) 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

(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, 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

(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

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