Skip to content

OpenAPI

enable_openapi 

enable_openapi() -> None

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

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

  • Request body from spec.input_serializer, a bare dataclass being auto-wrapped in DataclassSerializer, built with whatever partial flag spec.partial resolves to so the documented body matches what actually validates.
  • Success response from spec.output_selector_spec.output_serializer, or a no-content response when that is unset and the action's default status is 204.
  • A 422 documenting ServiceErrorSerializer, as spec.document_service_error gates it.

Read surfaces (Selector*View and the read-side action mixins) lean on the base AutoSchema for their body: output_serializer is already wired through get_serializer_class(), which is what drf-spectacular reads natively. The one addition is _get_filter_parameters, contributing the query parameters for a SelectorSpec.filter_set, so moving a FilterSet from a view-level filterset_class + DjangoFilterBackend onto spec.filter_set leaves the generated OpenAPI unchanged.

User-supplied @extend_schema annotations always win, and @extend_schema(parameters=...) merges over the filter parameters exactly as it does for a view-level FilterSet.

ServiceErrorSerializer

Bases: Serializer

Single-field detail serializer that mirrors _ServiceAPIException.

Used by 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 _ServiceAPIException.