Skip to content

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, the ProblemDetail component always present, and the camelCase and problem-response schema hooks. Spread it into your own SPECTACULAR_SETTINGS and override what you must.
  • :class:WireAutoSchema — the operationId convention, read from :mod:rn_forge.web.openapi so 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 as REST_FRAMEWORK["DEFAULT_SCHEMA_CLASS"].
  • :func:problem_responses_hook — declares an application/problem+json response, referencing ProblemDetail, for every status the problem handler can render, on every operation that does not already declare one. The FastAPI binding's FastApiApp.openapi() closes the identical gap on its side.
  • The security-scheme extensions for :class:~rn_forge.django.auth.drf.principal.PrincipalBearerAuthentication and its Basic twin. drf-spectacular discovers extensions by import, so importing this module — which naming :class:WireAutoSchema in 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 status relation points at.

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.