Skip to content

OpenAPI

enable_openapi 

enable_openapi() -> None

Set :class:ServiceAutoSchema as the schema on every library view class.

Call once from AppConfig.ready() (or anywhere after Django apps are loaded) to make drf-spectacular see ServiceSpec request bodies, response bodies, success statuses, and 422 contracts on:

  • ServiceCreateView, ServiceUpdateView, ServiceDeleteView
  • SelectorListView, SelectorRetrieveView
  • ServiceViewSet, SelectorViewSet

The function-local imports keep drf-spectacular an optional dependency: importing :mod:rest_framework_services.openapi does not require it, and only this call brings in the schema-generator code.

User subclasses inherit schema = ServiceAutoSchema() automatically; classes that set schema = ... explicitly keep their own choice.

ServiceAutoSchema

Bases: AutoSchema

AutoSchema that derives its request / response from a ServiceSpec.

For mutation surfaces (standalone Service*View classes, the ServiceViewSet action mixins, and @service_action):

  • Request body is derived from spec.input_serializer (a bare dataclass is auto-wrapped in :class:DataclassSerializer).
  • Response body for the success status is derived from spec.output_serializer (or rendered as a no-content response when unset and the action's default status is 204).
  • A 422 response documenting :class:ServiceErrorSerializer is attached so consumers know about the ServiceError contract.
  • Partial-update actions instantiate the request serializer with partial=True so optional-on-PATCH semantics show up correctly.

Read surfaces (Selector*View and the read-side action mixins) are left to the base AutoSchema: their output_serializer is already wired through get_serializer_class() and that's what drf-spectacular reads natively.

User-supplied @extend_schema annotations always win — they're consulted upstream of get_request_serializer / get_response_serializers.

ServiceErrorSerializer

Bases: Serializer

Single-field detail serializer that mirrors _ServiceAPIException.

Used by :class:ServiceAutoSchema to attach a 422 response to every spec-driven mutation in the generated OpenAPI document. It is only used for schema generation; runtime 422 bodies are produced by DRF's exception handler from :class:~rest_framework_services.views.mutation.utils._ServiceAPIException.