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]
|
|
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 |
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.