# drf-spectacular

> Sane and flexible OpenAPI 3 schema generation for Django REST framework

- **URL**: https://www.freshcrate.ai/projects/drf-spectacular
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `0.29.0` (2026-04-21)
- **License**: Unknown
- **Source**: https://github.com/tfranzel/drf-spectacular
- **Homepage**: https://pypi.org/project/drf-spectacular/
- **Language**: Python
- **GitHub**: 2,826 stars, 319 forks
- **Registry**: pypi (`drf-spectacular`)
- **Tags**: `api`, `django`, `openapi`, `pypi`, `rest`, `schema`, `swagger`

## Description

===============
drf-spectacular
===============

|build-status| |codecov| |docs| |pypi-version| |pypi-dl|

Sane and flexible `OpenAPI`_ (`3.0.3`_ & `3.1`_) schema generation for `Django REST framework`_.

This project has 3 goals:
    1. Extract as much schema information from DRF as possible.
    2. Provide flexibility to make the schema usable in the real world (not only toy examples).
    3. Generate a schema that works well with the most popular client generators.

The code is a heavily modified fork of the
`DRF OpenAPI generator <https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/openapi.py/>`_,
which is/was lacking all of the below listed features.

Features
    - Serializers modelled as components. (arbitrary nesting and recursion supported)
    - `@extend_schema <https://drf-spectacular.readthedocs.io/en/latest/drf_spectacular.html#drf_spectacular.utils.extend_schema>`_ decorator for customization of APIView, Viewsets, function-based views, and ``@action``
        - additional parameters
        - request/response serializer override (with status codes)
        - polymorphic responses either manually with ``PolymorphicProxySerializer`` helper or via ``rest_polymorphic``'s PolymorphicSerializer)
        - ... and more customization options
    - Authentication support (DRF natives included, easily extendable)
    - Custom serializer class support (easily extendable)
    - `SerializerMethodField() <https://drf-spectacular.readthedocs.io/en/latest/customization.html#step-3-extend-schema-field-and-type-hints>`_ type via type hinting or ``@extend_schema_field``
    - i18n support
    - Tags extraction
    - Request/response/parameter examples
    - Description extraction from ``docstrings``
    - Vendor specification extensions (``x-*``) in info, operations, parameters, components, and security schemes
    - Sane fallbacks
    - Sane ``operation_id`` naming (based on path)
    - Schema serving with ``SpectacularAPIView`` (Redoc and Swagger-UI views are also available)
    - Optional input/output serializer component split
    - Callback operations
    - OpenAPI 3.1 support (via setting ``OAS_VERSION``)
    - Included support for:
        - `django-polymorphic <https://github.com/django-polymorphic/django-polymorphic>`_ / `django-rest-polymorphic <https://github.com/apirobot/django-rest-polymorphic>`_
        - `SimpleJWT <https://github.com/jazzband/djangorestframework-simplejwt>`_
        - `DjangoOAuthToolkit <https://github.com/jazzband/django-oauth-toolkit>`_
        - `djangorestframework-jwt <https://github.com/jpadilla/django-rest-framework-jwt>`_ (tested fork `drf-jwt <https://github.com/Styria-Digital/django-rest-framework-jwt>`_)
        - `dj-rest-auth <https://github.com/iMerica/dj-rest-auth>`_ (maintained fork of `django-rest-auth <https://github.com/Tivix/django-rest-auth>`_)
        - `djangorestframework-camel-case <https://github.com/vbabiy/djangorestframework-camel-case>`_ (via postprocessing hook ``camelize_serializer_fields``)
        - `django-filter <https://github.com/carltongibson/django-filter>`_
        - `drf-nested-routers <https://github.com/alanjds/drf-nested-routers>`_
        - `djangorestframework-recursive <https://github.com/heywbj/django-rest-framework-recursive>`_
        - `djangorestframework-dataclasses <https://github.com/oxan/djangorestframework-dataclasses>`_
        - `django-rest-framework-gis <https://github.com/openwisp/django-rest-framework-gis>`_
        - `Pydantic (>=2.0) <https://github.com/pydantic/pydantic>`_


For more information visit the `documentation <https://drf-spectacular.readthedocs.io/>`_.

License
-------

Provided by `T. Franzel <https://github.com/tfranzel>`_. `Licensed under 3-Clause BSD <https://github.com/tfranzel/drf-spectacular/blob/master/LICENSE>`_.

Requirements
------------

-  Python >= 3.7
-  Django (2.2, 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2)
-  Django REST Framework (3.10.3, 3.11, 3.12, 3.13, 3.14, 3.15, 3.16)

Installation
------------

Install using ``pip``\ ...

.. code:: bash

    $ pip install drf-spectacular

then add drf-spectacular to installed apps in ``settings.py``

.. code:: python

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


and finally register our spectacular AutoSchema with DRF.

.. code:: python

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

drf-spectacular ships with sane `default settings <https://drf-spectacular.readthedocs.io/en/latest/settings.html>`_
that should work reasonably well out of the box. It is not necessary to
specify any settings, but we recommend to specify at least some metadata.

.. code:: python

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

.. _self-contained-ui-installation:

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.29.0` | 2026-04-21 | Low | Imported from PyPI (0.29.0) |
| `0.28.0` | 2024-11-30 | Low | ## Important notes * Y-stream release due to the amount of small but important changes. * Pydantic users might see a slightly different schema due to the change in serialization method.  ## PRs * Add support for stateless user authentication in SimpleJWT by @wmeints in https://github.com/tfranzel/drf-spectacular/pull/1221 * Bump django from 4.2.10 to 4.2.11 in /requirements by @dependabot in https://github.com/tfranzel/drf-spectacular/pull/1205 * add choice field display method handling # |
| `0.27.2` | 2024-04-01 | Low | ## Important notes * Some bugfixes and some functionality gaps closed.  ## PRs * Update link to redoc settings by @OttoAndrey in https://github.com/tfranzel/drf-spectacular/pull/1154 * Fix ordered dict by @tfranzel in https://github.com/tfranzel/drf-spectacular/pull/1160 * Add auth extension for django-rest-knox by @callumgare in https://github.com/tfranzel/drf-spectacular/pull/1163 * remove official 3.6 support due to upstream breakage. by @tfranzel in https://github.com/tfranzel/drf-spe |
| `0.27.1` | 2024-01-18 | Low | ## Important notes * Fixed some OAS 3.1 corner cases and added support for ``Webhooks`` (3.1) in addition to existing ``Callbacks``  ## PRs * coerse Decimal to float format explicitly #1134 by @tfranzel in https://github.com/tfranzel/drf-spectacular/pull/1136 * Provide all fixed field names for the components object in ResolvedComponent.* constants by @sergei-maertens in https://github.com/tfranzel/drf-spectacular/pull/1138 * Optional setting for enum suffixes by @jrbeaumont in https://git |
| `0.27.0` | 2023-12-12 | Low | ## Important notes * Biggest release in quite some time that contains a bunch of long running PR that finally found their way into master. * We now officially support **OpenAPI 3.1** and **Pydantic>=2** * Quite a few bug fixes (thanks to all contributors ❤️) and improved typing * If you use a custom version of `postprocess_schema_enums`, you might want to also manually add `postprocess_schema_enum_id_removal`, to remove the temporary ids we had to add. By default this action is done automati |
| `0.26.5` | 2023-09-23 | Low | ## Important notes * Added helper function `forced_singular_serializer` to disable a list detection on an endpoint, that has been quite difficult to properly undo previously. This closes the functional gap for `@extend_schema_serializer(many=False)` in single-use (non-envelope) situations. * Several small bugfixes  ## PRs * add helper to disable viewset list detection #1064 by @tfranzel in https://github.com/tfranzel/drf-spectacular/pull/1065 * Use schema_url in SpectacularElementsView by |
| `0.26.4` | 2023-07-23 | Low | ## Important notes * some minor bugfixes as well as improvements to ``django-filter`` and ``django-polymorphic``. * it is now significantly easier to adapt serializer naming via ``AutoSchema`` subclassing.  ## PRs * Fixing Pydantic Extension by @sydney-runkle in https://github.com/tfranzel/drf-spectacular/pull/1021 * allow already supported lazy string in types #982 by @tfranzel in https://github.com/tfranzel/drf-spectacular/pull/1013 * add Authorization header for oauth2 in swagger ui sc |
| `0.26.3` | 2023-06-22 | Low | ## Important notes * No major changes but a multiude of small improvements. * We are now a lot more tolerant when it comes to writing extensions for non-standard classes (e.g. Pydantic). * There should be no unexpected schema changes except for when `djangorestframework_camel_case`'s Middleware is used.  ## PRs * docs(example): Fix wrong bool value in example by @schew2381 in https://github.com/tfranzel/drf-spectacular/pull/1001 * fix: Camelize query parameters by @dobro322 in https://git |
| `0.26.2` | 2023-04-15 | Low | ## Important notes * small bugfix release that also contains the new `OpenApiRequest` feature  ## PRs * Add OpenApiRequest for encoding options #714 #965 by @tfranzel in https://github.com/tfranzel/drf-spectacular/pull/966 * fix jwt cookie name settings not being recognised by @nixsiow in https://github.com/tfranzel/drf-spectacular/pull/972  ## New Contributors * @nixsiow made their first contribution in https://github.com/tfranzel/drf-spectacular/pull/972  **Full Changelog**: https:// |
| `0.26.1` | 2023-03-18 | Low | ## Important notes  - Small bugfix release that addresses an issue when turning off choice description generation - Improve/bugfix ``PolymorphicSerializer`` type field handling  ## PRs * Add PresentablePrimarKeyRelatedField schema for drf-exrta-fields blue… by @enjoy2000 in https://github.com/tfranzel/drf-spectacular/pull/957 * Fix test warnings by @Incred in https://github.com/tfranzel/drf-spectacular/pull/959  ## New Contributors * @enjoy2000 made their first contribution in https:// |

## Citation

- HTML: https://www.freshcrate.ai/projects/drf-spectacular
- Markdown: https://www.freshcrate.ai/projects/drf-spectacular.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/drf-spectacular/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._