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)

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

SwaggerMethod method => HasSwagger (NoContentVerb method :: Type)

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (NoContentVerb method) -> Swagger

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

Defined in Servant.Swagger.Internal

Methods

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

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

WithNamedContext combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

(KnownNat status, AllAccept cs, SwaggerMethod method, HasSwagger (UVerb method cs as)) => HasSwagger (UVerb method cs (WithStatus status NoContent ': as) :: Type)

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (UVerb method cs (WithStatus status NoContent ': as)) -> Swagger

(ToSchema a, HasStatus a, AllAccept cs, SwaggerMethod method, HasSwagger (UVerb method cs as)) => HasSwagger (UVerb method cs (a ': as) :: Type)

@since TODO

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (UVerb method cs (a ': as)) -> Swagger

HasSwagger (UVerb method cs ('[] :: [Type]) :: Type)

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (UVerb method cs '[]) -> Swagger

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

HttpVersion combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

(ToSchema a, Accept ct, HasSwagger sub, KnownSymbol (FoldDescription mods)) => HasSwagger (StreamBody' mods fr ct a :> sub :: Type)

This instance is an approximation.

Since: 1.1.7

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (StreamBody' mods fr ct a :> sub) -> Swagger

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

Defined in Servant.Swagger.Internal

Methods

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

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

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 :: Type)

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 :: Type)

Defined in Servant.Swagger.Internal

Methods

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

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

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 :: Type)

Defined in Servant.Swagger.Internal

Methods

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

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

IsSecure combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

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

HasSwagger sub => HasSwagger (Fragment a :> sub :: Type)

Fragment combinator does not change our specification at all.

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (Fragment a :> sub) -> Swagger

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

Defined in Servant.Swagger.Internal

Methods

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

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

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 :: Type)

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 :: Type)

Defined in Servant.Swagger.Internal

Methods

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

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

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 :: Type)

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) :: Type)

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) :: Type)

Defined in Servant.Swagger.Internal

Methods

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

(ToSchema a, Accept ct, KnownNat status, SwaggerMethod method) => HasSwagger (Stream method status fr ct a :: Type)

Since: 1.1.7

Defined in Servant.Swagger.Internal

Methods

toSwagger :: Proxy (Stream method status fr ct 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

:: forall a cs hs proxy method status. (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

:: forall nocontent cs hs proxy method status. (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.

mkEndpointNoContentVerb

Arguments

:: forall proxy method. SwaggerMethod method

=> FilePath

Endpoint path.

-> proxy (NoContentVerb method)

Method

-> Swagger

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.

addDefaultResponse400 :: ParamName -> Swagger -> Swagger

class SwaggerMethod method where

Methods, available for Swagger.

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)

combinePathItem :: PathItem -> PathItem -> PathItem

combineSwagger :: Swagger -> Swagger -> Swagger

class AllAccept cs where

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

Methods

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

Instances

(KnownSymbol sym, ToParamSchema a) => ToResponseHeader (Header sym a :: Type)

Defined in Servant.Swagger.Internal

Methods

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

class AllToResponseHeader hs where

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 :: Type)

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