drf-spectacular

While django-rest-knox auth extensions are supported natively, the Views may lack structure in the generated OpenAPI document. Use the provided blueprint to fix this.

Additionally, to ensure out-of-the-box compatibility with OpenAPI generators and Swagger UI, configure the standard Authorization header prefix in your settings:

REST_KNOX = {
    "AUTH_HEADER_PREFIX": "Bearer",
}

If you are migrating from drf-yasg, replace your decorators with the following drf-spectacular equivalents. Note the changes in argument names:

• Replace @swagger_auto_schema with @extend_schema.

  • operation_description $\rightarrow$ description
  • operation_summary $\rightarrow$ summary
  • manual_parameters and query_serializer $\rightarrow$ parameters
  • security $\rightarrow$ auth
  • request_body $\rightarrow$ request (use None instead of drf_yasg.utils.no_body)
  • method $\rightarrow$ methods
  • Additional arguments: exclude, operation, versions, examples.

• Replace @swagger_serializer_method with @extend_schema_field.

• Replace @method_decorator with @extend_schema_view to decorate entire views.

• Replace swagger_schema_field with @extend_schema_field or @extend_schema_serializer.

When migrating helper classes from drf-yasg to drf-spectacular, use these mappings:

• drf_yasg.openapi.Parameter $\rightarrow$ drf_spectacular.utils.OpenApiParameter.

  • in_ $\rightarrow$ location
  • schema $\rightarrow$ type
  • Use many=True to define an array (replaces the need for an Items class).

• drf_yasg.openapi.Response $\rightarrow$ drf_spectacular.utils.OpenApiResponse.

  • schema $\rightarrow$ response
  • Note: Use keyword arguments as the order of arguments differs.

• drf_yasg.openapi.Schema is no longer required; use a plain Python dict instead.

• Use drf_spectacular.utils.OpenApiExample to provide examples to @extend_schema.

If get_queryset() or get_serializer_class() depends on attributes not available during schema generation (like request.user), you must provide a fallback. Check for the swagger_fake_view attribute on the view and return an empty queryset of the correct model.

class XViewset(viewsets.ModelViewset):
    ...

    def get_queryset(self):
        if getattr(self, 'swagger_fake_view', False):
            return YourModel.objects.none()
        # your usual logic

While drf-yasg required manual description of authentication schemes, drf-spectacular automatically generates security definitions for many built-in DRF authentication classes and popular third-party packages.

To integrate custom authentication classes, implement the drf_spectacular.extensions.OpenApiAuthenticationExtension class.

Extensions register themselves automatically, but the Python interpreter must see them at least once. The most robust way to ensure detection is to collect extensions in a schema.py file within your main app and import that file in your app's ready() method inside apps.py.

# your_main_app_name/apps.py
class YourMainAppNameConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "your_main_app_name"

    def ready(self):
        import your_main_app_name.schema  # noqa: E402

Blueprints are schema fixes for libraries that do not play well with drf-spectacular's automatic introspection. To use a blueprint, copy the snippet into your codebase. The extensions register themselves automatically as long as the Python interpreter sees them.

It is best practice to collect your extensions in YOUR_MAIN_APP_NAME/schema.py and import that file in your YOUR_MAIN_APP_NAME/apps.py within the ready() method to ensure the environment is properly set up.

# your_main_app_name/apps.py
class YourMainAppNameConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "your_main_app_name"

    def ready(self):
        import your_main_app_name.schema  # noqa: E402

If your environment cannot access CDNs to retrieve Swagger UI or Redoc, install the sidecar extra. This provides the static files locally. You must add drf_spectacular_sidecar to INSTALLED_APPS and configure the SPECTACULAR_SETTINGS to use the SIDECAR shorthand.

$ pip install drf-spectacular[sidecar]

INSTALLED_APPS = [
    # ALL YOUR APPS
    'drf_spectacular',
    'drf_spectacular_sidecar',  # required for Django collectstatic discovery
]

SPECTACULAR_SETTINGS = {
    'SWAGGER_UI_DIST': 'SIDECAR',  # shorthand to use the sidecar instead
    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
    'REDOC_DIST': 'SIDECAR',
    # OTHER SETTINGS
}

Extensions in drf-spectacular register themselves automatically, but the Python interpreter must see them at least once. The most robust way to ensure extensions are loaded is to collect them in a schema.py file within your main app and import that file inside the ready() method of your AppConfig in apps.py.

# your_main_app_name/apps.py
class YourMainAppNameConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "your_main_app_name"

    def ready(self):
        import your_main_app_name.schema  # noqa: E402

To run the project's test suite, you can use the provided runtests.py script or tox for testing against multiple Python and Django versions.

1. Install testing requirements: pip install -r requirements.txt
2. Run tests using the local script: ./runtests.py
3. Alternatively, use tox (requires tox to be installed globally): tox

$ pip install -r requirements.txt
$ ./runtests.py
# OR
$ tox