Servant.OpenApi.Internal

Documentation

class HasOpenApi api where

Generate a OpenApi specification for a servant API.

To generate OpenApi 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 openapi3 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

myOpenApi :: OpenApi
myOpenApi = toOpenApi (Proxy :: Proxy MyAPI)

Methods

toOpenApi :: Proxy api -> OpenApi

Generate a OpenApi specification for a servant API.

Instances

HasOpenApi Raw

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy Raw -> OpenApi

HasOpenApi EmptyAPI

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy EmptyAPI -> OpenApi

OpenApiMethod method => HasOpenApi (NoContentVerb method :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (NoContentVerb method) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (a :<|> b) -> OpenApi

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

WithNamedContext combinator does not change our specification at all.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (WithNamedContext x c sub) -> OpenApi

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

@since 2.0.1.0

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (UVerb method cs (a ': as)) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (UVerb method cs '[]) -> OpenApi

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

HttpVersion combinator does not change our specification at all.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (HttpVersion :> sub) -> OpenApi

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

This instance is an approximation.

Since: 1.1.7

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (StreamBody' mods fr ct a :> sub) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (ReqBody' mods cs a :> sub) -> OpenApi

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

RemoteHost combinator does not change our specification at all.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (RemoteHost :> sub) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (QueryParam' mods sym a :> sub) -> OpenApi

(KnownSymbol sym, ToParamSchema a, HasOpenApi sub) => HasOpenApi (QueryParams sym a :> sub :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (QueryParams sym a :> sub) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (QueryFlag sym :> sub) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Header' mods sym a :> sub) -> OpenApi

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

IsSecure combinator does not change our specification at all.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (IsSecure :> sub) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Summary desc :> api) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Description desc :> api) -> OpenApi

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

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Capture' mods sym a :> sub) -> OpenApi

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

OpenApi Spec doesn't have a notion of CaptureAll, this instance is the best effort.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (CaptureAll sym a :> sub) -> OpenApi

HasOpenApi sub => HasOpenApi (Vault :> sub :: Type)

Vault combinator does not change our specification at all.

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Vault :> sub) -> OpenApi

(KnownSymbol sym, HasOpenApi sub) => HasOpenApi (sym :> sub :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (sym :> sub) -> OpenApi

(AllAccept cs, KnownNat status, OpenApiMethod method) => HasOpenApi (Verb method status cs NoContent :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Verb method status cs NoContent) -> OpenApi

(ToSchema a, AllAccept cs, KnownNat status, OpenApiMethod method) => HasOpenApi (Verb method status cs a :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Verb method status cs a) -> OpenApi

(AllAccept cs, AllToResponseHeader hs, KnownNat status, OpenApiMethod method) => HasOpenApi (Verb method status cs (Headers hs NoContent) :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Verb method status cs (Headers hs NoContent)) -> OpenApi

(ToSchema a, AllAccept cs, AllToResponseHeader hs, KnownNat status, OpenApiMethod method) => HasOpenApi (Verb method status cs (Headers hs a) :: Type)

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Verb method status cs (Headers hs a)) -> OpenApi

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

Since: 1.1.7

Defined in Servant.OpenApi.Internal

Methods

toOpenApi :: Proxy (Stream method status fr ct a) -> OpenApi

subOperations

Arguments

:: (IsSubAPI sub api, HasOpenApi sub)

=> Proxy sub

Part of a servant API.

-> Proxy api

The whole servant API.

-> Traversal' OpenApi 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, OpenApiMethod method, KnownNat status)

=> FilePath

Endpoint path.

-> proxy (Verb method status cs (Headers hs a))

Method, content-types, headers and response.

-> OpenApi

Make a singleton OpenApi 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, OpenApiMethod method, KnownNat status)

=> FilePath

Endpoint path.

-> proxy (Verb method status cs (Headers hs nocontent))

Method, content-types, headers and response.

-> OpenApi

Make a singletone OpenApi spec (with only one endpoint) and with no content schema.

mkEndpointWithSchemaRef :: forall cs hs proxy method status a. (AllAccept cs, AllToResponseHeader hs, OpenApiMethod method, KnownNat status) => Maybe (Referenced Schema) -> FilePath -> proxy (Verb method status cs (Headers hs a)) -> OpenApi

Like mkEndpoint but with explicit schema reference. Unlike mkEndpoint this function does not update definitions.

mkEndpointNoContentVerb

Arguments

:: forall proxy method. OpenApiMethod method

=> FilePath

Endpoint path.

-> proxy (NoContentVerb method)

Method

-> OpenApi

addParam :: Param -> OpenApi -> OpenApi

Add parameter to every operation in the spec.

addRequestBody :: RequestBody -> OpenApi -> OpenApi

Add RequestBody to every operations in the spec.

markdownCode :: Text -> Text

Format given text as inline code in Markdown.

addDefaultResponse404 :: ParamName -> OpenApi -> OpenApi

addDefaultResponse400 :: ParamName -> OpenApi -> OpenApi

class OpenApiMethod method where

Methods, available for OpenApi.

Methods

openApiMethod :: proxy method -> Lens' PathItem (Maybe Operation)

Instances

OpenApiMethod 'PATCH

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'OPTIONS

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'DELETE

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'PUT

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'HEAD

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'POST

Defined in Servant.OpenApi.Internal

Methods

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

OpenApiMethod 'GET

Defined in Servant.OpenApi.Internal

Methods

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

class AllAccept cs where

Methods

allContentType :: Proxy cs -> [MediaType]

Instances

AllAccept ('[] :: [k])

Defined in Servant.OpenApi.Internal

Methods

allContentType :: Proxy '[] -> [MediaType]

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

Defined in Servant.OpenApi.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.OpenApi.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.OpenApi.Internal

Methods

toAllResponseHeaders :: Proxy '[] -> InsOrdHashMap HeaderName Header

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

Defined in Servant.OpenApi.Internal

Methods

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

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

Defined in Servant.OpenApi.Internal

Methods

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

Orphan instances

ToSchema a => ToSchema (WithStatus s a)

Methods

declareNamedSchema :: Proxy (WithStatus s a) -> Declare (Definitions Schema) NamedSchema