Servant.Swagger.Internal

servant-swagger-1.1.3.1: Generate Swagger specification for your servant API.

Safe Haskell | None
Language | Haskell2010

Servant.Swagger.Internal

Synopsis

- class HasSwagger api where
- subOperations :: (IsSubAPI sub api, HasSwagger sub) => Proxy sub -> Proxy api -> Traversal' Swagger Operation
- mkEndpoint :: forall a cs hs proxy method status. (ToSchema a, AllAccept cs, AllToResponseHeader hs, SwaggerMethod method, KnownNat status) => FilePath -> proxy (Verb method status cs (Headers hs a)) -> Swagger
- mkEndpointNoContent :: forall nocontent cs hs proxy method status. (AllAccept cs, AllToResponseHeader hs, SwaggerMethod method, KnownNat status) => FilePath -> proxy (Verb method status cs (Headers hs nocontent)) -> Swagger
- 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
- addParam :: Param -> Swagger -> Swagger
- addConsumes :: [MediaType] -> Swagger -> Swagger
- markdownCode :: Text -> Text
- addDefaultResponse404 :: ParamName -> Swagger -> Swagger
- addDefaultResponse400 :: ParamName -> Swagger -> Swagger
- class SwaggerMethod method where
- class AllAccept cs where
- class ToResponseHeader h where
- class AllToResponseHeader hs where

# 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 * EmptyAPI # |
Methods toSwagger :: Proxy EmptyAPI api -> Swagger #
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 #