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

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy Raw -> Swagger

HasSwagger EmptyAPI

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy EmptyAPI -> Swagger

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

Defined in Servant.Swagger.Internal

Methods

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

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

WithNamedContext combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

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

HttpVersion combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

RemoteHost combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

IsSecure combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (Capture' mods sym a :> sub) -> 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.

Defined in Servant.Swagger.Internal

Methods

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

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

Vault combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

(AllAccept cs, KnownNat status, SwaggerMethod method) => HasSwagger (Verb method status cs NoContent :: *)

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (Verb method status cs (Headers hs a)) -> 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 PATCH

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod OPTIONS

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod DELETE

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod PUT

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod HEAD

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod POST

Defined in Servant.Swagger.Internal

Methods

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

SwaggerMethod GET

Defined in Servant.Swagger.Internal

Methods

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

class AllAccept cs where

Minimal complete definition

allContentType

Methods

allContentType :: Proxy cs -> [MediaType]

Instances

AllAccept ([] :: [k])

Defined in Servant.Swagger.Internal

Methods

allContentType :: Proxy [] -> [MediaType]

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

Defined in Servant.Swagger.Internal

Methods

allContentType :: Proxy (c ': 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 :: *)

Defined in Servant.Swagger.Internal

Methods

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

class AllToResponseHeader hs where

Minimal complete definition

toAllResponseHeaders

Methods

toAllResponseHeaders :: Proxy hs -> InsOrdHashMap HeaderName Header

Instances

AllToResponseHeader ([] :: [k])

Defined in Servant.Swagger.Internal

Methods

toAllResponseHeaders :: Proxy [] -> InsOrdHashMap HeaderName Header

AllToResponseHeader hs => AllToResponseHeader (HList hs :: *)

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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