[numbata]

Summary

OpenAPI 3 documents now describe what each endpoint returns: status codes, descriptions, headers and the shape of the returned models. Together with the earlier steps this produces a complete document for typical Grape APIs, including those using entities and model parsers. Typos in symbolic statuses are reported instead of silently producing a broken document.

Problem solved

Consumers of an API description need to know what comes back and in what shape. Responses have to point at the models registered under components.schemas, as single objects, arrays or root-wrapped objects, with the right status and headers.

What changes

Responses are built from success, failure, http_codes and default_response. Responses reference the models registered under components.schemas (model exposure, composition and discriminators are handled by the core builder in the earlier step); response headers (including items, example and collectionFormat, which becomes the simple style), file downloads and the add_root wrapper are supported, and any truthy add_root uses the default root name as in Swagger 2.0. Symbolic statuses become HTTP codes.

Drawbacks and nuances

• An unknown symbolic status (for example :not_foud) warns once on stderr and is skipped; an unknown success symbol falls back to 200.
• The warning registry is process-wide and guarded by a mutex, so a symbol warns once per process, not once per API.
• 3.x components lack the model description that Swagger 2.0 definitions carry.
• Nullable entity exposures are marked with x: { nullable: true }; a plain documentation: { nullable: true } on an exposure is not forwarded by the entity parser.
• Response building is kept in one layer because status handling, headers and root wrapping share the same helpers.

Alternatives considered

• Raise on an unknown status: stricter, but documentation is rebuilt per request and a typo would take the endpoint down.
• Warn on every build: noisy, since documentation is regenerated per request.
• Split response objects from the models they reference: the references would point at nothing in the intermediate step.

Stacks on: pr/4-builder-params-bodies.

[github-actions]

Danger Report

No issues found.

View run