OpenAPI Generation

crateRouter.toOpenApi walks every registered CrateRule and returns an OpenAPI document. Because the rules are the same objects that drive routing, the document describes the API that is actually served rather than a hand-maintained copy.

import crate.generators.openapi;

auto api = crateRouter.toOpenApi;

std.file.write("openapi.json", api.serializeToJson.toPrettyString);

Operation Ids

Every operation gets a stable, unique operationId. Two rules decide it, in order:

1. Registered id. When a router registered the operation under an explicit id, the router stamps rule.operationId as <id>For<Model> — widgetCatalog on space becomes widgetCatalogForSpace.
2. Path-derived. Otherwise the id is built from the HTTP method and the path segments: pathOperationId.

Method and path	operationId
POST /articles	postArticles
POST /articles/:id	postArticlesItemById
POST /articles/publish	postPublishForArticles
POST /articles/:id/publish	postPublishForArticlesItemById
POST /pictures/:id/picture/png/512	postPicturePng512ForPicturesItemById

The two schemes are deliberately shaped differently. /spaces/:id/widgetCatalog registered by id and a custom operation class named after /spaces/:id/widget-catalog would otherwise collide on the same documentation name; For-joining the registered id keeps them apart.

Responses

Each rule contributes its success response under its status code, plus one entry per distinct status code in rule.errorResponses. Where several error responses share a status code they are merged into a single entry.

A response with no description of its own is documented as [no description] — the value of the noResponseDescription enum in crate.base. It is a placeholder, not a valid description: seeing it in a generated document means the rule needs a response.description.

rule.response.description = "The article was queued for publishing.";

Path Parameters

Path segments are described automatically. A segment named :id becomes a parameter documented as The `id` path segment. Model fields carry their own @describe and @example annotations into the schema, so documenting a field documents it everywhere it appears.

Schemas

toOpenApiSchema maps a ModelFields description onto an OpenAPI Schema, recursing through nested structs and arrays. Field names use their public form, so a field renamed for the wire is documented under the name clients actually send.

Related

• Policy system — where CrateRule comes from
• Custom Operations — registering operations under an explicit id