drf-spectacular

https://drf-spectacular.readthedocs.io/en/latest/
Admin
drf-spectacular is a Django REST Framework library that generates sane and flexible OpenAPI 3...
Tokens:28,987
Snippets:323
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Setup development environment

Source: https://drf-spectacular.readthedocs.io/en/latest/contributing.html

Commands to clone the repository, set up a virtual environment, install dependencies, and run the test suite.

```bash
$ # fork the repo on github
$ git clone https://github.com/YOURGITHUBNAME/drf-spectacular
$ cd drf-spectacular
$ python -m venv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt
(venv) $ ./runtests.py  # runs tests (pytest) & linting (isort, flake8, mypy)
```

--------------------------------

### Install testing requirements

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Install the necessary dependencies for running tests.

```bash
$ pip install -r requirements.txt
```

--------------------------------

### Install drf-spectacular via pip

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Install the package using pip.

```bash
$ pip install drf-spectacular
```

--------------------------------

### GET /schema/redoc/

Source: https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html

The SpectacularRedocView serves the Redoc interface for viewing API documentation.

```APIDOC
## GET /schema/redoc/

### Description
Serves the Redoc documentation interface.

### Method
GET

### Endpoint
/schema/redoc/
```

--------------------------------

### Install drf-spectacular-sidecar

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Install the sidecar package for environments without internet access.

```bash
$ pip install drf-spectacular[sidecar]
```

--------------------------------

### GET /schema/swagger-ui/

Source: https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html

The SpectacularSwaggerView serves the Swagger UI interface for interactive API documentation.

```APIDOC
## GET /schema/swagger-ui/

### Description
Serves the Swagger UI documentation interface.

### Method
GET

### Endpoint
/schema/swagger-ui/
```

--------------------------------

### GET /schema/

Source: https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html

The SpectacularAPIView serves the generated OpenAPI schema. It is the primary endpoint for retrieving the API specification.

```APIDOC
## GET /schema/

### Description
Retrieves the generated OpenAPI schema for the project.

### Method
GET

### Endpoint
/schema/
```

--------------------------------

### Custom Preprocessing Hook Example

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/customization.rst.txt

Define a custom preprocessing hook to alter the list of API endpoints before schema generation. This function receives a list of endpoints and should return the modified list.

```python
def custom_preprocessing_hook(endpoints):
    # your modifications to the list of operations that are exposed in the schema
    for (path, path_regex, method, callback) in endpoints:
        pass
    return endpoints
```

--------------------------------

### Generate Schema and Serve UI via CLI

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Use the management command to generate a YAML schema file and a Docker container to serve the Swagger UI.

```bash
$ ./manage.py spectacular --color --file schema.yml
$ docker run -p 8080:8080 -e SWAGGER_JSON=/schema.yml -v ${PWD}/schema.yml:/schema.yml swaggerapi/swagger-ui
```

--------------------------------

### Serve in-memory binary files

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Implement a custom BaseRenderer and use the bytes type in @extend_schema to document binary responses.

```python
from django.http import HttpResponse
from rest_framework.renderers import BaseRenderer


class BinaryRenderer(BaseRenderer):
    media_type = "application/octet-stream"
    format = "bin"


class FileViewSet(RetrieveModelMixin, GenericViewSet):
    ...
    renderer_classes = [BinaryRenderer]

    @extend_schema(responses=bytes)
    def retrieve(self, request, *args, **kwargs):
        export_data = b"..."
        return HttpResponse(
            export_data,
            content_type=BinaryRenderer.media_type,
            headers={
                "Content-Disposition": "attachment; filename=out.bin",
            },
        )
```

--------------------------------

### Configure Sidecar in settings.py

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Register the sidecar app and update settings to use local static files.

```python
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
}
```

--------------------------------

### Decorate Serializer with extend_schema_serializer

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/customization.rst.txt

Apply `@extend_schema_serializer` to exclude fields from the schema or provide request/response examples. Useful for complex serializers or envelope patterns.

```python
@extend_schema_serializer(
    exclude_fields=('single',), # schema ignore these fields
    examples = [
         OpenApiExample(
            'Valid example 1',
            summary='short summary',
            description='longer description',
            value={
                'songs': {'top10': True},
                'single': {'top10': True}
            },
            # request_only=True, # signal that example only applies to requests
            # response_only=True, # signal that example only applies to responses
        ),
    ]
)
class AlbumSerializer(serializers.ModelSerializer):
    songs = SongSerializer(many=True)
    single = SongSerializer(read_only=True)

    class Meta:
        fields = '__all__'
        model = Album
```

--------------------------------

### Serve In-Memory Generated Files with BinaryRenderer

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

Create a custom BinaryRenderer with media_type 'application/octet-stream' and format 'bin'. Use this renderer and HttpResponse with Content-Disposition header to serve binary data as a file attachment.

```python
from django.http import HttpResponse
from rest_framework.renderers import BaseRenderer


class BinaryRenderer(BaseRenderer):
    media_type = "application/octet-stream"
    format = "bin"


class FileViewSet(RetrieveModelMixin, GenericViewSet):
    ... 
    renderer_classes = [BinaryRenderer]

    @extend_schema(responses=bytes)
    def retrieve(self, request, *args, **kwargs):
        export_data = b"..."
        return HttpResponse(
            export_data,
            content_type=BinaryRenderer.media_type,
            headers={
                "Content-Disposition": "attachment; filename=out.bin",
            },
        )
```

--------------------------------

### Register drf-spectacular in settings.py

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Add the library to the INSTALLED_APPS list in your Django settings.

```python
INSTALLED_APPS = [
    # ALL YOUR APPS
    'drf_spectacular',
]
```

--------------------------------

### Custom Postprocessing Hook Example

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/customization.rst.txt

Implement a custom hook to modify the generated OpenAPI root object. This function receives the result, generator instance, request, and a public flag, returning the modified result.

```python
from typing import Any, Dict, Optional

def custom_postprocessing_hook(
    result: Dict[str, Any],
    generator: "SchemaGenerator",
    request: Optional["HttpRequest"],
    public: bool,
) -> Dict[str, Any]:
    """
    result: the OpenAPI root object, e.g.:
    {
        "openapi": "3.0.3",
        "info": {"title": "API", "version": "1.0.0"},
        "paths": {},
        "components": {"schemas": {}, "parameters": {}, "responses": {}},
    }
    generator: the SchemaGenerator instance (access registry, etc.)
    request: the HTTP request that triggered schema generation, or None
    public: True when generating a public schema (excludes internal endpoints)
    """
    return result
```

--------------------------------

### Run tests with runtests.py

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Execute the project test suite using the provided runtests script.

```bash
$ ./runtests.py
```

--------------------------------

### Configuring multiple SpectacularAPIView instances

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Use the custom_settings argument to provide scoped overrides for specific schema views.

```python
urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(),
    path('api/schema-custom/', SpectacularAPIView.as_view(
        custom_settings={
            'TITLE': 'your custom title',
            'SCHEMA_PATH_PREFIX': 'your custom regex',
            ...
        }
    ), name='schema-custom'),
]
```

--------------------------------

### Configure CSP for Redoc

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Settings to resolve blank Redoc pages when using django-csp, including required worker and font source configurations.

```python
# Option: SIDECAR
SPECTACULAR_SETTINGS = {
     ...
    'REDOC_DIST': 'SIDECAR',
}
# Option: CDN
CSP_DEFAULT_SRC = ("'self'", "cdn.jsdelivr.net")

# required for both CDN and SIDECAR
CSP_WORKER_SRC = ("'self'", "blob:")
CSP_IMG_SRC = ("'self'", "data:", "cdn.redoc.ly")
CSP_STYLE_SRC = ("'self'", "'unsafe-inline'", "fonts.googleapis.com")
CSP_FONT_SRC = ("'self'", "fonts.gstatic.com")
```

--------------------------------

### Configure Component Settings

Source: https://drf-spectacular.readthedocs.io/en/latest/client_generation.html

Settings to manage how components are split and handled to assist client generators with read-only and required fields.

```python
# Split components into request and response parts where appropriate
'COMPONENT_SPLIT_REQUEST': False,
# Aid client generator targets that have trouble with read-only properties.
'COMPONENT_NO_READ_ONLY_REQUIRED': False,
# Create separate components for PATCH endpoints (without required list)
'COMPONENT_SPLIT_PATCH': True,
```

--------------------------------

### Configure Django CSP for Redoc UI with CDN

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

When using CDN assets for Redoc UI, configure CSP_DEFAULT_SRC, CSP_WORKER_SRC, CSP_IMG_SRC, CSP_STYLE_SRC, and CSP_FONT_SRC to include the CDN domain.

```python
CSP_DEFAULT_SRC = ("'self'", "cdn.jsdelivr.net")

# required for both CDN and SIDECAR
CSP_WORKER_SRC = ("'self'", "blob:")
CSP_IMG_SRC = ("'self'", "data:", "cdn.redoc.ly")
CSP_STYLE_SRC = ("'self'", "'unsafe-inline'", "fonts.googleapis.com")
CSP_FONT_SRC = ("'self'", "fonts.gstatic.com")
```

--------------------------------

### Configuring manual security schemes

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/blueprints.rst.txt

Manually define security schemes in SPECTACULAR_SETTINGS when automatic introspection fails for specific authentication libraries.

```python
SPECTACULAR_SETTINGS = {
    "APPEND_COMPONENTS": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "Authorization"
            }
        }
    },
    "SECURITY": [{"ApiKeyAuth": [], }],
     ...
}
```

--------------------------------

### Configure API Schema and UI Views

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Add schema and UI view paths to your Django URL configuration to expose the API documentation.

```python
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
urlpatterns = [
    # YOUR PATTERNS
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI:
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]
```

--------------------------------

### Run tests with tox

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Use tox to run tests across multiple Python and Django versions.

```bash
$ tox
```

--------------------------------

### Define SPECTACULAR_SETTINGS

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Optional metadata configuration for the generated API schema.

```python
SPECTACULAR_SETTINGS = {
    'TITLE': 'Your Project API',
    'DESCRIPTION': 'Your project description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    # OTHER SETTINGS
}
```

--------------------------------

### Configure Django CSP for Redoc UI with SIDECAR

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

For Redoc UI with the SIDECAR option, configure CSP_DEFAULT_SRC, CSP_WORKER_SRC, CSP_IMG_SRC, CSP_STYLE_SRC, and CSP_FONT_SRC appropriately.

```python
SPECTACULAR_SETTINGS = {
     ...
    'REDOC_DIST': 'SIDECAR',
}
# Option: CDN
CSP_DEFAULT_SRC = ("'self'", "cdn.jsdelivr.net")

# required for both CDN and SIDECAR
CSP_WORKER_SRC = ("'self'", "blob:")
CSP_IMG_SRC = ("'self'", "data:", "cdn.redoc.ly")
CSP_STYLE_SRC = ("'self'", "'unsafe-inline'", "fonts.googleapis.com")
CSP_FONT_SRC = ("'self'", "fonts.gstatic.com")
```

--------------------------------

### Configure SwaggerUI Settings in Django

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/settings.rst.txt

Use SPECTACULAR_SETTINGS to pass configuration parameters to SwaggerUI. Customize options like deep linking and authorization persistence. Ensure SWAGGER_UI_DIST points to the correct Swagger UI distribution.

```python
SPECTACULAR_SETTINGS = {
    ...
    # available SwaggerUI configuration parameters
    # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
    "SWAGGER_UI_SETTINGS": {
        "deepLinking": True,
        "persistAuthorization": True,
        "displayOperationId": True,
        ...
    },
    # available SwaggerUI versions: https://github.com/swagger-api/swagger-ui/releases
    "SWAGGER_UI_DIST": "https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest", # default
    "SWAGGER_UI_FAVICON_HREF": settings.STATIC_URL + "your_company_favicon.png", # default is swagger favicon
    ...
}
```

--------------------------------

### Define Multiple SpectacularAPIView with Custom Settings

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

Use custom_settings argument in SpectacularAPIView.as_view to provide scoped overrides for settings. Note that this is not thread-safe and certain settings like SERVE_* or DEFAULT_GENERATOR_CLASS cannot be overridden this way.

```python
urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(),
    path('api/schema-custom/', SpectacularAPIView.as_view(
        custom_settings={
            'TITLE': 'your custom title',
            'SCHEMA_PATH_PREFIX': 'your custom regex',
            ...
        }
    ), name='schema-custom'),
]
```

--------------------------------

### Configure CSP for Swagger UI

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Settings to resolve blank Swagger UI pages when using django-csp, offering both SIDECAR and CDN configuration options.

```python
# Option: SIDECAR
SPECTACULAR_SETTINGS = {
     ...
    'SWAGGER_UI_DIST': 'SIDECAR',
    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
}
CSP_DEFAULT_SRC = ("'self'", "'unsafe-inline'")
CSP_IMG_SRC = ("'self'", "data:")

# Option: CDN
CSP_DEFAULT_SRC = ("'self'", "'unsafe-inline'", "cdn.jsdelivr.net")
CSP_IMG_SRC = ("'self'", "data:", "cdn.jsdelivr.net")
```

--------------------------------

### Migrating Docstring Parsing to @extend_schema

Source: https://drf-spectacular.readthedocs.io/en/latest/drf_yasg.html

Demonstrates how to replace drf-yasg docstring splitting with explicit summary and description arguments in drf-spectacular.

```python
# Supported by drf-yasg:
class UserViewSet(ViewSet):
    def list(self, request):
        """
        List all the users.

        Return a list of all usernames in the system.
        """
        ...

# Updated for drf-spectacular using decorator for description:
class UserViewSet(ViewSet):
    @extend_schema(
        summary="List all the users.",
        description="Return a list of all usernames in the system.",
    )
    def list(self, request):
        ...

# Updated for drf-spectacular using docstring for description:
class UserViewSet(ViewSet):
    @extend_schema(summary="List all the users.")
    def list(self, request):
        """Return a list of all usernames in the system."""
        ...
```

--------------------------------

### Authentication Handling

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/drf_yasg.rst.txt

Explains the difference in how authentication schemes are documented between drf-yasg and drf-spectacular.

```APIDOC
## Authentication Handling

### Description
`drf-yasg` requires manual description of authentication schemes. In contrast, `drf-spectacular` supports auto-generation of security definitions for common DRF authentication classes and provides `OpenApiAuthenticationExtension` for custom authentication integration.

### drf-yasg Authentication

*   Manually describe authentication schemes.
*   Refer to `drf-yasg`'s security documentation for details.

### drf-spectacular Authentication

*   Supports auto-generation of security definitions for built-in DRF authentication classes.
*   Supports popular third-party authentication packages.
*   Provides `drf_spectacular.extensions.OpenApiAuthenticationExtension` for custom authentication schemes.
*   Refer to the `customization guide <customization_authentication_extension>` for integration details.
```

--------------------------------

### Import Schema Extensions in Django AppConfig

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

Import your schema extensions in the ready() method of your AppConfig for robust loading. This ensures the environment is set up before extensions are loaded.

```python
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
```

--------------------------------

### Implement SpectacularElementsView

Source: https://drf-spectacular.readthedocs.io/en/latest/blueprints.html

A custom APIView that renders the Elements documentation template using DRF Spectacular settings.

```python
from rest_framework.renderers import TemplateHTMLRenderer
from rest_framework.response import Response
from rest_framework.reverse import reverse
from rest_framework.views import APIView

from drf_spectacular.plumbing import get_relative_url, set_query_parameters
from drf_spectacular.settings import spectacular_settings
from drf_spectacular.utils import extend_schema
from drf_spectacular.views import AUTHENTICATION_CLASSES


class SpectacularElementsView(APIView):
    renderer_classes = [TemplateHTMLRenderer]
    permission_classes = spectacular_settings.SERVE_PERMISSIONS
    authentication_classes = AUTHENTICATION_CLASSES
    url_name = 'schema'
    url = None
    template_name = 'elements.html'
    title = spectacular_settings.TITLE

    @extend_schema(exclude=True)
    def get(self, request, *args, **kwargs):
        return Response(
            data={
                'title': self.title,
                'js_dist': 'https://unpkg.com/@stoplight/elements/web-components.min.js',
                'css_dist': 'https://unpkg.com/@stoplight/elements/styles.min.css',
                'schema_url': self._get_schema_url(request),
            },
            template_name=self.template_name
        )

    def _get_schema_url(self, request):
        schema_url = self.url or get_relative_url(reverse(self.url_name, request=request))
        return set_query_parameters(
            url=schema_url,
            lang=request.GET.get('lang'),
            version=request.GET.get('version')
        )
```

--------------------------------

### Docstring Handling Comparison

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/drf_yasg.rst.txt

Illustrates how drf-yasg and drf-spectacular handle docstrings for operation summaries and descriptions, and the recommended approach for drf-spectacular using `@extend_schema`.

```APIDOC
## Docstring Handling

### Description
Compares how `drf-yasg` and `drf-spectacular` parse docstrings for API operation details. `drf-yasg` splits the first line for summary and the rest for description. `drf-spectacular` uses the entire docstring as description by default, recommending the use of `summary` and `description` arguments within `@extend_schema` for explicit control.

### drf-yasg Docstring Handling

```python
class UserViewSet(ViewSet):
    def list(self, request):
        """
        List all the users.

        Return a list of all usernames in the system.
        """
        ...
```

### drf-spectacular Docstring Handling (Recommended)

#### Using `@extend_schema` for Summary and Description

```python
from drf_spectacular.utils import extend_schema

class UserViewSet(ViewSet):
    @extend_schema(
        summary="List all the users.",
        description="Return a list of all usernames in the system.",
    )
    def list(self, request):
        ...
```

#### Using `@extend_schema` for Summary and Docstring for Description

```python
from drf_spectacular.utils import extend_schema

class UserViewSet(ViewSet):
    @extend_schema(summary="List all the users.")
    def list(self, request):
        """Return a list of all usernames in the system."""
        ...
```

### Named Sections Comparison

`drf-yasg` supports `named sections` in docstrings, which `drf-spectacular` does not directly support. The `summary` and `description` arguments of `@extend_schema` should be used instead.

#### drf-yasg Named Sections

```python
class UserViewSet(ViewSet):
    """
    list:
        List all the users.

        Return a list of all usernames in the system.

    retrieve:
        Retrieve user

        Get details of a specific user
    """
    ...
```

#### drf-spectacular Equivalent using `@extend_schema_view`

```python
from drf_spectacular.utils import extend_schema, extend_schema_view

@extend_schema_view(
    list=extend_schema(
        summary="List all the users.",
        description="Return a list of all usernames in the system.",
    ),
    retrieve=extend_schema(
        summary="Retrieve user",
        description="Get details of a specific user",
    ),
)
class UserViewSet(ViewSet):
    ...
```
```

--------------------------------

### Implement OpenApiViewExtension for Missing Queryset

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/customization.rst.txt

Use `OpenApiViewExtension` to provide a `queryset` for views that lack one or have a dynamic queryset. This allows drf-spectacular to infer the model for schema generation.

```python
class Fix4(OpenApiViewExtension):
    target_class = 'oscarapi.views.checkout.UserAddressDetail'

    def view_replacement(self):
        from oscar.apps.address.models import UserAddress

        class Fixed(self.target_class):
            # Example 1: missing or dynamic information
            queryset = UserAddress.objects.none()
```

--------------------------------

### Create rapidoc.html Template

Source: https://drf-spectacular.readthedocs.io/en/latest/blueprints.html

The HTML template file used by the view to load the RapiDoc web component.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title|default:"RapiDoc" }}</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script type="module" src="{{ dist }}/dist/rapidoc-min.js"></script>
  </head>
  <body>
    <rapi-doc spec-url="{{ schema_url }}"></rapi-doc>
  </body>
</html>
```

--------------------------------

### Configure Django App for Schema Extensions

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/customization.rst.txt

Import schema extensions in your Django app's `apps.py` `ready()` method to ensure they are registered automatically. This is crucial for extensions to hook into schema generation.

```python
# 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
```

--------------------------------

### Create elements.html Template

Source: https://drf-spectacular.readthedocs.io/en/latest/blueprints.html

The HTML template required to load the Elements web components and display the API documentation.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title|default:"Elements" }}</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <script src="{{ js_dist }}"></script>
    <link rel="stylesheet" href="{{ css_dist }}">
  </head>
  <body>
    <elements-api apiDescriptionUrl="{{ schema_url }}" router="hash" />
  </body>
</html>
```

--------------------------------

### Configure Django CSP for Swagger UI with SIDECAR

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

When using the SIDECAR option for Swagger UI, configure CSP_DEFAULT_SRC and CSP_IMG_SRC to allow self and data URIs.

```python
SPECTACULAR_SETTINGS = {
     ...
    'SWAGGER_UI_DIST': 'SIDECAR',
    'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
}
CSP_DEFAULT_SRC = ("'self'", "'unsafe-inline'")
CSP_IMG_SRC = ("'self'", "data:")
```

--------------------------------

### Configure Django CSP for Swagger UI with CDN

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

When using CDN assets for Swagger UI, update CSP_DEFAULT_SRC and CSP_IMG_SRC to include the CDN domain.

```python
CSP_DEFAULT_SRC = ("'self'", "'unsafe-inline'", "cdn.jsdelivr.net")
CSP_IMG_SRC = ("'self'", "data:", "cdn.jsdelivr.net")
```

--------------------------------

### Configure Component Splitting for Request/Response

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/client_generation.rst.txt

Enables splitting components into separate request and response parts to handle issues with readOnly, writeOnly, and required fields, improving client code clarity and reducing misuse. Set to True to resolve most common component-related client generation problems.

```python
'COMPONENT_SPLIT_REQUEST': False,
```

--------------------------------

### Replacing Views with OpenApiViewExtension

Source: https://drf-spectacular.readthedocs.io/en/latest/customization.html

Use view_replacement to provide missing queryset or serializer_class information for third-party views during schema generation.

```python
class Fix4(OpenApiViewExtension):
    target_class = 'oscarapi.views.checkout.UserAddressDetail'

    def view_replacement(self):
        from oscar.apps.address.models import UserAddress

        class Fixed(self.target_class):
            # Example 1: missing or dynamic information
            queryset = UserAddress.objects.none()
            # Example 2: another example for a common issue
            serializer_class = AvailabilitySerializer
        return Fixed
```

--------------------------------

### Generate schema for a specific API version

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Use this command to include unversioned endpoints along with those matching the specified version.

```bash
./manage.py spectacular --api-version 'YOUR_VERSION'
```

--------------------------------

### Generate drf-spectacular schema for a specific API version

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

Use the 'spectacular' management command with the '--api-version' argument to generate a schema for a specific version, including unversioned endpoints.

```bash
./manage.py spectacular --api-version 'YOUR_VERSION'
```

--------------------------------

### Configure Type Settings

Source: https://drf-spectacular.readthedocs.io/en/latest/client_generation.html

Controls the emission of additionalProperties in the schema to accommodate generator sensitivity.

```python
# Determines if and how free-form 'additionalProperties' should be emitted in the schema. Some
# code generator targets are sensitive to this. None disables generic 'additionalProperties'.
# allowed values are 'dict', 'bool', None
'GENERIC_ADDITIONAL_PROPERTIES': 'dict',
```

--------------------------------

### Configure No Read-Only Required Fields

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/client_generation.rst.txt

Addresses client generator issues with read-only properties, particularly when they are also required. This setting can water down schema correctness, so using COMPONENT_SPLIT_REQUEST is generally recommended instead.

```python
'COMPONENT_NO_READ_ONLY_REQUIRED': False,
```

--------------------------------

### Configure AutoSchema in REST_FRAMEWORK

Source: https://drf-spectacular.readthedocs.io/en/latest/readme.html

Register the spectacular AutoSchema as the default schema class.

```python
REST_FRAMEWORK = {
    # YOUR SETTINGS
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
```

--------------------------------

### Internationalize schema documentation

Source: https://drf-spectacular.readthedocs.io/en/latest/faq.html

Apply Django's gettext_lazy to view docstrings and @extend_schema parameters to support schema internationalization.

```python
from django.utils.translation import gettext_lazy as _

class PersonView(viewsets.GenericViewSet):
    __doc__ = _("""
    More lengthy explanation of the view
    """)

    @extend_schema(summary=_('Main endpoint for creating person'))
    def retrieve(self, request, *args, **kwargs):
        pass
```

--------------------------------

### Implement django-oscar-api extensions

Source: https://drf-spectacular.readthedocs.io/en/latest/blueprints.html

A collection of extension classes to override view and serializer behavior for drf-spectacular schema generation.

```python
from rest_framework import serializers

from drf_spectacular.extensions import (
    OpenApiSerializerExtension, OpenApiSerializerFieldExtension, OpenApiViewExtension
)
from drf_spectacular.plumbing import build_basic_type
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, extend_schema, extend_schema_field


class Fix1(OpenApiViewExtension):
    target_class = 'oscarapi.views.root.api_root'

    def view_replacement(self):
        return extend_schema(responses=OpenApiTypes.OBJECT)(self.target_class)


class Fix2(OpenApiViewExtension):
    target_class = 'oscarapi.views.product.ProductAvailability'

    def view_replacement(self):
        from oscarapi.serializers.product import AvailabilitySerializer

        class Fixed(self.target_class):
            serializer_class = AvailabilitySerializer
        return Fixed


class Fix3(OpenApiViewExtension):
    target_class = 'oscarapi.views.product.ProductPrice'

    def view_replacement(self):
        from oscarapi.serializers.checkout import PriceSerializer

        class Fixed(self.target_class):
            serializer_class = PriceSerializer
        return Fixed


class Fix4(OpenApiViewExtension):
    target_class = 'oscarapi.views.checkout.UserAddressDetail'

    def view_replacement(self):
        from oscar.apps.address.models import UserAddress

        class Fixed(self.target_class):
            queryset = UserAddress.objects.none()
        return Fixed


class Fix5(OpenApiViewExtension):
    target_class = 'oscarapi.views.product.CategoryList'

    def view_replacement(self):
        class Fixed(self.target_class):
            @extend_schema(parameters=[
                OpenApiParameter(name='breadcrumbs', type=OpenApiTypes.STR, location=OpenApiParameter.PATH)
            ])
            def get(self, request, *args, **kwargs):
                pass

        return Fixed


class Fix6(OpenApiSerializerExtension):
    target_class = 'oscarapi.serializers.checkout.OrderSerializer'

    def map_serializer(self, auto_schema, direction):
        from oscarapi.serializers.checkout import OrderOfferDiscountSerializer, OrderVoucherOfferSerializer

        class Fixed(self.target_class):
            @extend_schema_field(OrderOfferDiscountSerializer(many=True))
            def get_offer_discounts(self):
                pass

            @extend_schema_field(OpenApiTypes.URI)
            def get_payment_url(self):
                pass

            @extend_schema_field(OrderVoucherOfferSerializer(many=True))
            def get_voucher_discounts(self):
                pass

        return auto_schema._map_serializer(Fixed, direction)


class Fix7(OpenApiSerializerFieldExtension):
    target_class = 'oscarapi.serializers.fields.CategoryField'

    def map_serializer_field(self, auto_schema, direction):
        return build_basic_type(OpenApiTypes.STR)


class Fix8(OpenApiSerializerFieldExtension):
    target_class = 'oscarapi.serializers.fields.AttributeValueField'

    def map_serializer_field(self, auto_schema, direction):
        return {
            'oneOf': [
                build_basic_type(OpenApiTypes.STR),
            ]
        }


class Fix9(OpenApiSerializerExtension):
    target_class = 'oscarapi.serializers.basket.BasketSerializer'

    def map_serializer(self, auto_schema, direction):
        class Fixed(self.target_class):
            is_tax_known = serializers.SerializerMethodField()

            def get_is_tax_known(self) -> bool:
                pass

        return auto_schema._map_serializer(Fixed, direction)


class Fix10(Fix9):
    target_class = 'oscarapi.serializers.basket.BasketLineSerializer'
```

--------------------------------

### Configure Component Splitting for PATCH Requests

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/client_generation.rst.txt

Enables separate component creation for PATCH requests to handle clashes with the 'required' property, which cannot be adequately modeled with a single component. This setting is enabled by default.

```python
'COMPONENT_SPLIT_PATCH': True,
```

--------------------------------

### Compatibility Features

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/drf_yasg.rst.txt

Details compatibility features implemented in drf-spectacular for drf-yasg users, such as `ref_name` and `swagger_fake_view`.

```APIDOC
## Compatibility Features

### Description
`drf-spectacular` implements several features for compatibility with `drf-yasg`.

### `ref_name` on `Serializer` `Meta` Classes

- **Supported**: `drf-spectacular` supports `ref_name` on `Serializer` `Meta` classes, excluding inlining with `ref_name=None`.
- **`drf-yasg` Reference**: See `drf-yasg's documentation <drf-yasg:swagger_schema_fields>`.
- **`drf-spectacular` Equivalent**: Use `@extend_schema_serializer(component_name="...")`.

### `swagger_fake_view`

- **Supported**: `drf-spectacular` supports `swagger_fake_view` as an attribute on views to signal schema generation, similar to `drf-yasg`.
```

--------------------------------

### drf-yasg Docstring Handling vs drf-spectacular

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/drf_yasg.rst.txt

drf-yasg splits docstrings for summary and description. drf-spectacular uses the entire docstring as description. Use `@extend_schema` for explicit summary and description.

```python
# Supported by drf-yasg:
class UserViewSet(ViewSet):
    def list(self, request):
        """
        List all the users.

        Return a list of all usernames in the system.
        """
        ...

```

```python
# Updated for drf-spectacular using decorator for description:
class UserViewSet(ViewSet):
    @extend_schema(
        summary="List all the users.",
        description="Return a list of all usernames in the system.",
    )
    def list(self, request):
        ...

```

```python
# Updated for drf-spectacular using docstring for description:
class UserViewSet(ViewSet):
    @extend_schema(summary="List all the users.")
    def list(self, request):
        """Return a list of all usernames in the system."""
        ...

```

--------------------------------

### Configure SPECTACULAR_SETTINGS in Django

Source: https://drf-spectacular.readthedocs.io/en/latest/settings.html

Define the SPECTACULAR_DEFAULTS dictionary in your Django settings.py file to override default schema generation and UI behaviors.

```python
SPECTACULAR_DEFAULTS: Dict[str, Any] = {
    # A regex specifying the common denominator for all operation paths. If
    # SCHEMA_PATH_PREFIX is set to None, drf-spectacular will attempt to estimate
    # a common prefix. Use '' to disable.
    # Mainly used for tag extraction, where paths like '/api/v1/albums' with
    # a SCHEMA_PATH_PREFIX regex '/api/v[0-9]' would yield the tag 'albums'.
    'SCHEMA_PATH_PREFIX': None,
    # Remove matching SCHEMA_PATH_PREFIX from operation path. Usually used in
    # conjunction with appended prefixes in SERVERS.
    'SCHEMA_PATH_PREFIX_TRIM': False,
    # Insert a manual path prefix to the operation path, e.g. '/service/backend'.
    # Use this for example to align paths when the API is mounted as a sub-resource
    # behind a proxy and Django is not aware of that. Alternatively, prefixes can
    # also specified via SERVERS, but this makes the operation path more explicit.
    'SCHEMA_PATH_PREFIX_INSERT': '',
    # Coercion of {pk} to {id} is controlled by SCHEMA_COERCE_PATH_PK. Additionally,
    # some libraries (e.g. drf-nested-routers) use "_pk" suffixed path variables.
    # This setting globally coerces path variables like "{user_pk}" to "{user_id}".
    'SCHEMA_COERCE_PATH_PK_SUFFIX': False,

    # Schema generation parameters to influence how components are constructed.
    # Some schema features might not translate well to your target.
    # Demultiplexing/modifying components might help alleviate those issues.
    'DEFAULT_GENERATOR_CLASS': 'drf_spectacular.generators.SchemaGenerator',
    # Create separate components for PATCH endpoints (without required list)
    'COMPONENT_SPLIT_PATCH': True,
    # Split components into request and response parts where appropriate
    # This setting is highly recommended to achieve the most accurate API
    # description, however it comes at the cost of having more components.
    'COMPONENT_SPLIT_REQUEST': False,
    # Aid client generator targets that have trouble with read-only properties.
    'COMPONENT_NO_READ_ONLY_REQUIRED': False,

    # Adds "minLength: 1" to fields that do not allow blank strings. Deactivated
    # by default because serializers do not strictly enforce this on responses and
    # so "minLength: 1" may not always accurately describe API behavior.
    # Gets implicitly enabled by COMPONENT_SPLIT_REQUEST, because this can be
    # accurately modeled when request and response components are separated.
    'ENFORCE_NON_BLANK_FIELDS': False,

    # This version string will end up the in schema header. The default OpenAPI
    # version is 3.0.3, which is heavily tested. We now also support 3.1.0,
    # which contains the same features and a few mandatory, but minor changes.
    'OAS_VERSION': '3.0.3',

    # Configuration for serving a schema subset with SpectacularAPIView
    'SERVE_URLCONF': None,
    # complete public schema or a subset based on the requesting user
    'SERVE_PUBLIC': True,
    # include schema endpoint into schema
    'SERVE_INCLUDE_SCHEMA': True,
    # list of authentication/permission classes for spectacular's views.
    'SERVE_PERMISSIONS': ['rest_framework.permissions.AllowAny'],
    # None will default to DRF's AUTHENTICATION_CLASSES
    'SERVE_AUTHENTICATION': None,

    # Dictionary of general configuration to pass to the SwaggerUI({ ... })
    # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
    # The settings are serialized with json.dumps(). If you need customized JS, use a
    # string instead. The string must then contain valid JS and is passed unchanged.
    'SWAGGER_UI_SETTINGS': {
        'deepLinking': True,
    },
    # Initialize SwaggerUI with additional OAuth2 configuration.
    # https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/
    'SWAGGER_UI_OAUTH2_CONFIG': {},

    # Dictionary of general configuration to pass to the Redoc.init({ ... })
    # https://redocly.com/docs/redoc/config/#functional-settings
    # The settings are serialized with json.dumps(). If you need customized JS, use a
    # string instead. The string must then contain valid JS and is passed unchanged.
    'REDOC_UI_SETTINGS': {},

    # CDNs for swagger and redoc. You can change the version or even host your
    # own depending on your requirements. For self-hosting, have a look at
    # the sidecar option in the README.
    'SWAGGER_UI_DIST': 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest',
    'SWAGGER_UI_FAVICON_HREF': 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/favicon-32x32.png',
    'REDOC_DIST': 'https://cdn.jsdelivr.net/npm/redoc@latest',

    # Append OpenAPI objects to path and components in addition to the generated objects
    'APPEND_PATHS': {},
    'APPEND_COMPONENTS': {},
}
```

--------------------------------

### Internationalize Schema and UI with Django's i18n

Source: https://drf-spectacular.readthedocs.io/en/latest/_sources/faq.rst.txt

Leverage Django's internationalization settings (USE_I18N=True, languages, makemessages, compilemessages) for schema and UI translations. The CLI tool and schema view support language parameters or query parameters.

```python
from django.utils.translation import gettext_lazy as _

class PersonView(viewsets.GenericViewSet):
    __doc__ = _("""
    More lengthy explanation of the view
    """)

    @extend_schema(summary=_('Main endpoint for creating person'))
    def retrieve(self, request, *args, **kwargs):
        pass
```
Tokens:
Raw