Safe Haskell	None
Language	GHC2021

Ecluse.Core.Server.RouteDescription

Contents

The documented view
Projection from a route
The synthetic catch-all

Description

The documented operation view of a route, as plain OpenAPI-free data.

specsOf erases an Ecluse.Core.Server.Route.Route into the operations the OpenAPI spec needs. A write route contributes PUT, a submission route POST, and a removal route DELETE. A read route contributes both GET and its derived bodiless HEAD operation. The capture type, builder, and typed response value disappear. Each operation's ResponseDocs still come from the same ResponseContract runtime dispatch uses.

Synopsis

data RouteSpec = RouteSpec {
- rsName :: RouteName
- rsMethod :: StdMethod
- rsPattern :: [PathSeg]
- rsSummary :: Text
- rsDescription :: Text
- rsRequest :: Maybe RequestSpec
- rsOutcomes :: [ResponseDoc]
}
data PathSeg
- = Lit Text
- | Param ParamSpec
data ParamSpec = ParamSpec {
- psName :: Text
- psDescription :: Text
}
specsOf :: Route v -> [RouteSpec]
catchAllSpecs :: ResponseContract r -> ParamSpec -> NonEmpty RouteSpec
unsupportedPathParam :: ParamSpec

The documented view

data RouteSpec Source #

One served HTTP operation, as the manifest documents it. No Eq or Show: request and response schemas may carry autodocodec codecs, which are functions.

Constructors

RouteSpec

Fields

rsName :: RouteName
The operation name within its ecosystem. A HEAD projection adds a .head suffix.
rsMethod :: StdMethod
The exact HTTP method this operation serves.
rsPattern :: [PathSeg]
The mount-relative path template.
rsSummary :: Text
A one-line summary.
rsDescription :: Text
The fuller operation description.
rsRequest :: Maybe RequestSpec
The accepted request body, when any.
rsOutcomes :: [ResponseDoc]
The responses projected from the operation's runtime contract.

data PathSeg Source #

One literal or captured path segment.

Constructors

Lit Text
Param ParamSpec

Instances

Instances details

Show PathSeg Source #
Instance details Defined in Ecluse.Core.Server.RouteDescription Methods showsPrec :: Int -> PathSeg -> ShowS # show :: PathSeg -> String # showList :: [PathSeg] -> ShowS #
Eq PathSeg Source #
Instance details Defined in Ecluse.Core.Server.RouteDescription Methods (==) :: PathSeg -> PathSeg -> Bool # (/=) :: PathSeg -> PathSeg -> Bool #

data ParamSpec Source #

A named path parameter and its human-facing description.

Constructors

ParamSpec
Fields psName :: Text The name as it appears in the template. psDescription :: Text A one-line description.

Instances

Instances details

Show ParamSpec Source #
Instance details Defined in Ecluse.Core.Server.RouteDescription Methods showsPrec :: Int -> ParamSpec -> ShowS # show :: ParamSpec -> String # showList :: [ParamSpec] -> ShowS #
Eq ParamSpec Source #
Instance details Defined in Ecluse.Core.Server.RouteDescription Methods (==) :: ParamSpec -> ParamSpec -> Bool # (/=) :: ParamSpec -> ParamSpec -> Bool #

Projection from a route

specsOf :: Route v -> [RouteSpec] Source #

Project a route to every exact method it serves. The HEAD contract is the bodilessContract reading of the response value GET uses, so its status set cannot drift from the GET's.

The synthetic catch-all

catchAllSpecs :: ResponseContract r -> ParamSpec -> NonEmpty RouteSpec Source #

The GET and HEAD pair documenting a mount's deny-by-default catch-all. It is the absence of a match rather than a route, so no Route carries it and each table appends it.

unsupportedPathParam :: ParamSpec Source #

The catch-all's path parameter, as every mount's route table documents it.