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

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

AllAccept [*] cs => HasSwagger * (Get cs ())

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs) => HasSwagger * (Get cs (Headers hs a))

(ToSchema a, AllAccept [*] cs) => HasSwagger * (Get cs a)

AllAccept [*] cs => HasSwagger * (Post cs ())

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs) => HasSwagger * (Post cs (Headers hs a))

(ToSchema a, AllAccept [*] cs) => HasSwagger * (Post cs a)

AllAccept [*] cs => HasSwagger * (Delete cs ())

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs) => HasSwagger * (Delete cs (Headers hs a))

(ToSchema a, AllAccept [*] cs) => HasSwagger * (Delete cs a)

AllAccept [*] cs => HasSwagger * (Put cs ())

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs) => HasSwagger * (Put cs (Headers hs a))

(ToSchema a, AllAccept [*] cs) => HasSwagger * (Put cs a)

AllAccept [*] cs => HasSwagger * (Patch cs ())

(ToSchema a, AllAccept [*] cs, AllToResponseHeader [*] hs) => HasSwagger * (Patch cs (Headers hs a))

(ToSchema a, AllAccept [*] cs) => HasSwagger * (Patch cs a)

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

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

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

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

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

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

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

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 :: forall a cs hs proxy _verb. (ToSchema a, AllAccept cs, AllToResponseHeader hs) => FilePath -> Lens' PathItem (Maybe Operation) -> HttpStatusCode -> proxy (_verb cs (Headers hs a)) -> Swagger

noContentEndpoint :: forall cs proxy verb. AllAccept cs => FilePath -> Lens' PathItem (Maybe Operation) -> proxy (verb cs ()) -> Swagger

mkEndpointWithSchemaRef :: forall cs hs proxy verb a. (AllAccept cs, AllToResponseHeader hs) => Maybe (Referenced Schema) -> FilePath -> Lens' PathItem (Maybe Operation) -> HttpStatusCode -> proxy (verb cs (Headers hs a)) -> 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.

addDefaultResponse404 :: ParamName -> Swagger -> Swagger

addDefaultResponse400 :: ParamName -> Swagger -> Swagger

class AllAccept cs where

Methods

allContentType :: Proxy cs -> [MediaType]

Instances

AllAccept [k] ([] k)

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

class ToResponseHeader h where

Methods

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

Instances

(KnownSymbol sym, ToParamSchema a) => ToResponseHeader * (Header sym a)

class AllToResponseHeader hs where

Methods

toAllResponseHeaders :: Proxy hs -> HashMap HeaderName Header

Instances

AllToResponseHeader [*] hs => AllToResponseHeader * (HList hs)

AllToResponseHeader [k] ([] k)

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