OpenAPI
Requires the openapi extra. See the OpenAPI guide.
rn_forge.django.drf.openapi
OpenAPI through drf-spectacular, held to the same conventions as the FastAPI stack.
Requires the openapi extra. Not re-exported from any facade; import it
directly.
Four things an application otherwise gets wrong, each shipped as code:
- :data:
SPECTACULAR_SETTINGS— OpenAPI 3.1.0, camelCase names, theProblemDetailcomponent always present, and the camelCase and problem-response schema hooks. Spread it into your ownSPECTACULAR_SETTINGSand override what you must. - :class:
WireAutoSchema— theoperationIdconvention, read from :mod:rn_forge.web.openapiso that this stack and the FastAPI one apply one rule rather than two copies of it. A generated client gets the same method names on either — document text otherwise is not held identical across stacks; drf-spectacular's own paginated-component name is kept. Name it asREST_FRAMEWORK["DEFAULT_SCHEMA_CLASS"]. - :func:
problem_responses_hook— declares anapplication/problem+jsonresponse, referencingProblemDetail, for every status the problem handler can render, on every operation that does not already declare one. The FastAPI binding'sFastApiApp.openapi()closes the identical gap on its side. - The security-scheme extensions for
:class:
~rn_forge.django.auth.drf.principal.PrincipalBearerAuthenticationand its Basic twin. drf-spectacular discovers extensions by import, so importing this module — which naming :class:WireAutoSchemain settings does — registers them.
The djangorestframework_camel_case postprocessing hook drf-spectacular
documents is not used; :func:camelize_schema_hook is its replacement, for the
reason given in :mod:rn_forge.django.drf.casing.
OPENAPI_VERSION = '3.1.0'
module-attribute
The OpenAPI version both stacks emit. 3.0 and 3.1 differ in nullability.
SPECTACULAR_SETTINGS = {'OAS_VERSION': OPENAPI_VERSION, 'CAMELIZE_NAMES': True, 'APPEND_COMPONENTS': {'schemas': {'ProblemDetail': ProblemDetail.model_json_schema(mode='serialization')}}, 'POSTPROCESSING_HOOKS': ['drf_spectacular.hooks.postprocess_schema_enums', 'rn_forge.django.drf.openapi.camelize_schema_hook', 'rn_forge.django.drf.openapi.problem_responses_hook']}
module-attribute
drf-spectacular settings every rn-forge-django API starts from.
Usage::
from rn_forge.django.drf.openapi import SPECTACULAR_SETTINGS as RNF_SPECTACULAR
SPECTACULAR_SETTINGS = {**RNF_SPECTACULAR, "TITLE": "Orders API"}
PrincipalBasicAuthenticationScheme
Bases: OpenApiAuthenticationExtension
Declares PrincipalBasicAuthentication as an HTTP basic security scheme.
PrincipalBearerAuthenticationScheme
Bases: OpenApiAuthenticationExtension
Declares PrincipalBearerAuthentication as an HTTP bearer security scheme.
WireAutoSchema
Bases: AutoSchema
drf-spectacular's AutoSchema, named by the kit's operationId convention.
Read from :mod:rn_forge.web.openapi, which the FastAPI binding reads too:
<resource><Verb> in lowerCamelCase for CRUD, and <resource><Action>
for an AIP-136 custom method spelled /orders/<str:pk>:cancel. An action
spelled as a plain path segment gets a mechanical name; give it an explicit
@extend_schema(operation_id=...).
The paginated component keeps drf-spectacular's own name
(PaginatedOrderOutList) — document text is not held identical across
stacks; only wire behaviour and operationId are.
An operation of a :class:~rn_forge.django.drf.views.mixins.ReadMaskMixin
view that the mask applies to also documents the readMask query parameter.
A :class:~rn_forge.django.drf.views.mixins.SoftDeleteMixin view documents
showDeleted on its list, DELETE as a 200 with the resource, and
:undelete without a request body.
camelize_schema_hook(result, generator, request, public)
Camelize property names and required lists in every component schema.
The document then describes what the camelCase renderer actually emits.
openapi_urlpatterns(*, readiness_path=READINESS_PATH)
Return URL patterns serving the OpenAPI document, the docs UI, and the API catalog.
Mounts drf-spectacular's :class:~drf_spectacular.views.SpectacularAPIView
at :data:~rn_forge.web.OPENAPI_PATH (JSON) and
:class:~drf_spectacular.views.SpectacularSwaggerView at
:data:~rn_forge.web.DOCS_PATH, plus RFC 9727's
:data:~rn_forge.web.API_CATALOG_PATH, which points at both and at
readiness_path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
readiness_path
|
str
|
The path the catalog's |
READINESS_PATH
|
problem_responses_hook(result, generator, request, public)
Add an application/problem+json response, by status, to every operation.
Accuracy only, mirroring FastApiApp.openapi()'s repair on the FastAPI
side: an author's own responses= entry for that status is never
overwritten.