Skip to content

OpenAPI naming

rn_forge.web.openapi

Framework-independent OpenAPI operation naming and problem-response declarations.

API_CATALOG_PATH = '/.well-known/api-catalog' module-attribute

RFC 9727's well-known URI for the API catalog.

DOCS_PATH = '/docs' module-attribute

Default path of the human-readable documentation UI.

LINKSET_MEDIA_TYPE = 'application/linkset+json' module-attribute

The media type of an RFC 9264 linkset, which RFC 9727 requires for the catalog.

OPENAPI_PATH = '/openapi.json' module-attribute

Default path of the OpenAPI document.

PROBLEM_DETAIL_REF = '#/components/schemas/ProblemDetail' module-attribute

The $ref every declared problem response points at.

add_problem_responses(document, registry)

Declare a problem response for each of :func:problem_statuses on every operation.

Mutates document in place. A response the author already declared for a status is never overwritten. The ProblemDetail component itself is the caller's to add.

Parameters:

Name Type Description Default
document Mapping[str, Any]

An OpenAPI document, as a generator emitted it.

required
registry ProblemRegistry

The rows the application's problem handler renders with.

required

api_catalog_body(*, anchor, service_desc, service_doc=None, status=None)

Return the RFC 9727 /.well-known/api-catalog body.

An RFC 9264 linkset with one entry, following RFC 9727 §4's example: the machine-readable description (RFC 8631's service-desc relation, in practice the OpenAPI document) is required, and the human documentation (service-doc) and the API's status (status, in practice readiness) are added when given.

Parameters:

Name Type Description Default
anchor str

The API's base URI.

required
service_desc str

The OpenAPI document's URI.

required
service_doc str | None

The human documentation's URI.

None
status str | None

The status endpoint's URI.

None

Returns:

Type Description
dict[str, Any]

{"linkset": [{"anchor": ..., "service-desc": [{"href": ...}], ...}]}.

operation_id(path, method)

Return the operationId for path and method: <resource><Verb>.

The result is lower camel case. For CRUD, resource is the last literal path segment (/api/v1/work-items/{id} → workItems); Verb is List for a GET on a collection and Get for one on an item (the path ends in a parameter), Create for POST, Update for PUT, PartialUpdate for PATCH, and Delete for DELETE.

Custom methods follow AIP-136 <https://google.aip.dev/136>_: an action that is not one of the six above is addressed as :action on the resource it acts on, and is named <resource><Action> regardless of HTTP method. POST /orders/{orderId}:cancel → ordersCancel; POST /orders:batchCreate → ordersBatchCreate.

Routes that do not encode custom methods with the colon form require an explicit framework-specific override.

Parameters:

Name Type Description Default
path str

The route's path template, parameters in braces.

required
method str

The HTTP method, any case.

required

Returns:

Type Description
str

The operationId.

problem_response(status)

Return the OpenAPI response object for a problem with status.

problem_statuses(registry)

Return every status registry can render, plus 500, ascending.