Servant.Util.Swagger

Documentation

type family ParamDescription a :: Symbol

Description of parameter.

Unfortunatelly, servant-swagger package, when deriving description of an endpoint parameter, fills its description for you and makes you implement just ParamSchema which has no description field. To circumvent that you can define description in instance of this type family and later override swagger derivation accordingly.

type DescribedParam a = (ToParamSchema a, KnownSymbol (ParamDescription a))

paramDescription :: forall a proxy. KnownSymbol (ParamDescription a) => proxy a -> Text

Set description according to ParamDescription definition.

type family QueryFlagDescription (name :: Symbol) :: Symbol

Defines swagger description for the given QueryFlag parameter.

Instances

type QueryFlagDescription "onlyCount"

Defined in Servant.Util.Swagger

type QueryFlagDescription "onlyCount" = "If this parameter is present, return only the total count of items."

type family SwaggerrizeApi api where ...

This applies following transformations to API for the sake of better swagger documentation.

• Response of methods returning () is replaced with NoContents (otherwise invalid swagger is generated).
• Captures and QueryParams are attached a description according to ParamDescription type family (default description is empty).
• QueryFlag name occurences are attached descriptions according to ParamsDescription (QueryFlagDescription name) (there was no description by default).

Equations

SwaggerrizeApi ((path :: Symbol) :> api) = path :> SwaggerrizeApi api

SwaggerrizeApi (Capture' mods sym a :> api) = SwaggerCapture (Description (ParamDescription a) ': mods) sym a :> SwaggerrizeApi api

SwaggerrizeApi (QueryParam' mods sym a :> api) = SwaggerQueryParam (Description (ParamDescription a) ': mods) sym a :> SwaggerrizeApi api

SwaggerrizeApi (QueryFlag name :> api) = SwaggerQueryFlag name :> SwaggerrizeApi api

SwaggerrizeApi (arg :> api) = arg :> SwaggerrizeApi api

SwaggerrizeApi (api1 :<|> api2) = SwaggerrizeApi api1 :<|> SwaggerrizeApi api2

SwaggerrizeApi (Verb (method :: StdMethod) (code :: Nat) ctx ()) = Verb method code ctx NoContent

SwaggerrizeApi (Verb (method :: StdMethod) (code :: Nat) ctx a) = Verb method code ctx a

SwaggerrizeApi Raw = Raw

SwaggerrizeApi EmptyAPI = EmptyAPI