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

Safe HaskellNone
LanguageHaskell2010

Servant.Swagger.Internal

Synopsis

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.

class SwaggerMethod method where #

Methods, available for Swagger.

Minimal complete definition

swaggerMethod

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

Instances