drf-yasg
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django Rest Framework code.
Description
.. role:: python(code) :language: python ######################################## drf-yasg - Yet another Swagger generator ######################################## |actions| |nbsp| |codecov| |nbsp| |rtd-badge| |nbsp| |pypi-version| |nbsp| |gitter| Generate **real** Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API. Compatible with - **Django Rest Framework**: 3.13, 3.14, 3.15 - **Django**: 4.0, 4.1, 4.2, 5.0, 5.1, 5.2 - **Python**: 3.9, 3.10, 3.11, 3.12, 3.13 Only the latest patch version of each ``major.minor`` series of Python, Django and Django REST Framework is supported. **Only the latest version of drf-yasg is supported.** Support of old versions is dropped immediately with the release of a new version. Please do not create issues before upgrading to the latest release available at the time. Regression reports are accepted and will be resolved with a new release as quickly as possible. Removed features will usually go through a deprecation cycle of a few minor releases. Resources: * `Sources <https://github.com/axnsan12/drf-yasg>`_ * `Documentation <https://drf-yasg.readthedocs.io>`_ * `Changelog <https://drf-yasg.readthedocs.io/en/stable/changelog.html>`_ * `Discussion <https://app.gitter.im/#/room/#drf-yasg:gitter.im>`_ .. image:: https://img.shields.io/badge/live%20demo-blue?style=for-the-badge&logo=django :target: https://drf-yasg.com :alt: Live Demo **************** OpenAPI 3.0 note **************** If you are looking to add Swagger/OpenAPI support to a new project you might want to take a look at `drf-spectacular <https://github.com/tfranzel/drf-spectacular>`_, which is an actively maintained new library that shares most of the goals of this project, while working with OpenAPI 3.0 schemas. OpenAPI 3.0 provides a lot more flexibility than 2.0 in the types of API that can be described. ``drf-yasg`` is unlikely to soon, if ever, get support for OpenAPI 3.0. ******** Features ******** - full support for nested Serializers and Schemas - response schemas and descriptions - model definitions compatible with codegen tools - customization hooks at all points in the spec generation process - JSON and YAML format for spec - bundles latest version of `swagger-ui <https://github.com/swagger-api/swagger-ui>`_ and `redoc <https://github.com/Rebilly/ReDoc>`_ for viewing the generated documentation - schema view is cacheable out of the box - generated Swagger schema can be automatically validated by `swagger-spec-validator <https://github.com/Yelp/swagger_spec_validator>`_ - supports Django REST Framework API versioning with ``URLPathVersioning`` and ``NamespaceVersioning``; other DRF or custom versioning schemes are not currently supported .. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/redoc-nested-response.png :width: 100% :figwidth: image :alt: redoc screenshot **Fully nested request and response schemas.** .. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-list.png :width: 100% :figwidth: image :alt: swagger-ui screenshot **Choose between redoc and swagger-ui.** .. figure:: https://raw.githubusercontent.com/axnsan12/drf-yasg/1.0.2/screenshots/swagger-ui-models.png :width: 100% :figwidth: image :alt: model definitions screenshot **Real Model definitions.** ***************** Table of contents ***************** .. contents:: :depth: 4 ***** Usage ***** 0. Installation =============== The preferred installation method is directly from pypi: .. code:: console pip install --upgrade drf-yasg Additionally, if you want to use the built-in validation mechanisms (see `4. Validation`_), you need to install some extra requirements: .. code:: console pip install --upgrade drf-yasg[validation] .. _readme-quickstart: 1. Quickstart ============= In ``settings.py``: .. code:: python INSTALLED_APPS = [ ... 'django.contrib.staticfiles', # required for serving swagger ui's css/js files 'drf_yasg', ... ] In ``urls.py``: .. code:: python ... from django.urls import re_path from rest_framework import permissions from drf_yasg.views import get_schema_view from drf_yasg import openapi ... schema_view = get_schema_view( openapi.Info( title="Snippets API", default_version='v1', description="Test description", terms_of_service="https://www.google.com/policies/terms/", contact=openapi.Contact(email="contact@snippets.local"), license=openapi.License(name="BSD License"), ), public=True, permission_classes=(permissions.AllowAny,), ) urlpatterns = [ path('swagger.<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'), path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'), path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name=
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 1.21.15 | Imported from PyPI (1.21.15) | Low | 4/21/2026 |
| 1.21.14 | **FIXED:** Fix missing swagger-ui sourcemaps (#950) | Low | 1/15/2026 |
| 1.21.12 | **FIXED:** Bring the bundled swagger ui up to date (#944) **IMPROVED:** Update the logout button to use a POST request. (#945) **ADDED:** Add a live demo domain (#946) **ADDED:** Handle annotations that are not available at runtime (#941) | Low | 1/14/2026 |
| 1.21.11 | **FIXED:** Fix list views with parameters in last path segment not named "list" views (#917) **ADDED:** Allow overriding produces/consumes with @swagger_auto_schema decorator (#916) **FIXED:** Fix filter parameters not appearing in swagger with django-filter>=25 (#926) **IMPROVED:** Update Python, Django, and DRF versions and packaging configuration (#922) **IMPROVED:** Remove usage of pkg_resources (#928) **FIXED:** Fix call_view_method warning to include the method name again (#923) **AD | Low | 9/26/2025 |
| 1.21.10 | **FIXED:** Fix type hints when using postponed evaluation of annotations (PEP-563) (#840) **IMPROVED:** Update JSON & YAML renderers to not use a "." in their format string (#911) **FIXED:** Fix lint errors when comparing types with == instead of is (#868) **IMPROVED:** Update swagger-ui-dist to address CVE-2021-46708 (#904) | Low | 3/10/2025 |
| 1.21.9 | **ADDED:** Added support for zoneinfo object fields (#908) | Low | 3/7/2025 |
| 1.21.8 | **ADDED:** Python 3.11 and 3.12 support (#891) **FIXED:** Fix pkg_resources version lookups for Python 3.9+ (#891) | Low | 10/17/2024 |
| 1.21.7 | **ADDED:** Added ``drf_yasg.inspectors.query.DrfAPICompatInspector`` (#857) **ADDED:** Added ``DrfAPICompatInspector`` to serve as a replacement ``CoreAPICompatInspector`` (#857) **ADDED:** Allow ``DEFAULT_SPEC_RENDERERS`` default renderers to be overriden in the settings (#857) **FIXED:** Fixed redoc source mapping (#859) | Low | 10/17/2024 |
| 1.21.6 | **IMPROVED:** Remove required coreapi dependency (#854) **IMPROVED:** Feature: Migrate to PyYAML for yaml generator (#845) **FIXED:** Keep path parameters in their given order (#841) **FIXED:** Provide support for enums in codecs (#837) | Low | 10/17/2024 |
| 1.21.5 | **ADDED:** Python 3.10 support (#818) **DEPRECATED:** Python 3.6 support as it's been deprecated by swagger-spec-validator **FIXED:** RecursiveField resolver (#822) | Low | 2/9/2023 |
| 1.21.4 | **FIXED:** Remove NullBooleanFields if the django-rest-framework version >= 3.14.0 (#814) | Low | 9/27/2022 |
| 1.21.3 | **FIXED:** Set generator url for swagger_settings.DEFAULT_API_URL (#682) **FIXED:** Check fields for allow_null attribute (#688) **FIXED:** Encode pytz object field as a string by default (#717) **FIXED:** Handle errors rendering with TemplateHTMLRenderer (#742) | Low | 7/18/2022 |
| 1.21.2 | **FIXED:** Fixed code block rst syntax in ``README.rst`` (#797) | Low | 7/18/2022 |
| 1.21.1 | **FIXED:** Refer to permission_classes as a tuple (#678) **IMPROVED:** Document drf-extra-fields base64 integration (#445) **ADDED:** Added many support to example code (#695) **ADDED:** Allow specifying response as a reference (#757) **FIXED:** Fix old spelling errors and add a cspell configuration (#796) **FIXED:** Remove universal wheel, python 2 is unsupported (#782) **FIXED:** Fix duration field inspector (#549) | Low | 7/17/2022 |
| 1.21.0 | - **IMPROVED:** Add utf-8 support to yaml loaders (#692) | Low | 7/15/2022 |
| 1.20.3 | - **FIXED:** Source mapping in ``redoc.min.js`` (#778) - **FIXED:** Publish action tag pattern in ``publish.yml`` (#794) | Low | 7/15/2022 |
| 1.17.1 | *Release date: Feb 17, 2020* - **FIXED:** fixed compatibility issue with CurrentUserDefault in Django Rest Framework 3.11 - **FIXED:** respect `USERNAME_FIELD` in `generate_swagger` command (#486) **Support was dropped for Python 3.5, Django 2.0, Django 2.1, DRF 3.7** | Low | 10/25/2020 |
| 1.20.0 | - **IMPROVED:** updated ``swagger-ui`` to version 3.36.0 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.40 - **FIXED:** fixed compatibility with Django Rest Framework 3.12 - **FIXED:** fixed compatibility with Python 3.9 typing generics - **FIXED:** dropped support for obsolete ``django.conf.settings.LOGOUT_URL`` (#646) **Support was dropped for Python 2.7, DRF 3.8, DRF 3.9.** **Requirements are now: Python>=3.6, Django>=2.2, DRF>=3.10** The 1.18 and 1.19 series was skipped to | Low | 10/25/2020 |
| 1.17.0 | - **ADDED:** added `JSONFieldInspector` for `JSONField` support (#417) - **IMPROVED:** updated ``swagger-ui`` to version 3.23.11 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.14 (#398) - **FIXED:** fixed a type hint support issue (#428, #450) - **FIXED:** fixed packaging issue caused by a missing requirement (#412) | Low | 10/2/2019 |
| 1.16.1 | - **FIXED:** fixed DRF 3.10 compatibility (#408, #410, #411) - **IMPROVED:** better enum type detection for nested `ChoiceField`s (#400) | Low | 7/16/2019 |
| 1.16.0 | *Release date: Jun 13, 2019* - **ADDED:** added `reference_resolver_class` attribute hook to `SwaggerAutoSchema` (#350) - **ADDED:** added `operation_keys` attribute to `SwaggerAutoSchema`, along with `__init__` parameter (#355) - **FIXED:** fixed potential crash on `issubclass` check without `isclass` check | Low | 7/16/2019 |
| 1.15.1 | - **IMPROVED:** updated ``swagger-ui`` to version 3.22.3 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.8-1 - **FIXED:** fixed an issue with inspection of typing hints on Python 2.7 (#363) - **FIXED:** fixed an issue with inspection of typing hints on Python 3.7 (#371) **Python 3.4 support has been dropped!** | Low | 6/13/2019 |
| 1.15.0 | - **ADDED:** added ``is_list_view`` and ``has_list_response`` extension points to ``SwaggerAutoSchema`` (#331) - **IMPROVED:** updated ``swagger-ui`` to version 3.22.0 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.4 - **FIXED:** ``ListModelMixin`` will now always be treated as a list view (#306) - **FIXED:** non-primtive values in field ``choices`` will now be handled properly (#340) đ 400 commits đ | Low | 4/1/2019 |
| 1.14.0 | - **IMPROVED:** updated ``swagger-ui`` to version 3.21.0 - **FIXED:** implicit ``ref_name`` collisions will now throw an exception - **FIXED:** ``RecursiveField`` will now also work as a child of ``ListSerializer`` (#321) - **FIXED:** fixed ``minLength`` and ``maxLength`` for ``ListSerializer`` and ``ListField`` - **FIXED:** the ``items`` property of ``Schema``, ``Parameter`` and ``Items`` objects was renamed to ``items_``; this is a *mildly breaking change* and was needed to fix the collisi | Low | 3/3/2019 |
| 1.13.0 | - **IMPROVED:** type hint inspection is now supported for collections and ``Optional`` (#272) - **IMPROVED:** updated ``swagger-ui`` to version 3.20.5 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.2 - **DEPRECATED:** quietly dropped support for the ``flex`` validator; it will still work if the library is installed, but the setup.py requirement was removed and the validator will be silently skipped if not installed (#285) | Low | 3/3/2019 |
| 1.12.1 | - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-rc.0 - **FIXED:** management command will now correctly fall back to ``DEFAULT_VERSION`` for mock request - **FIXED:** fixed bad "raised exception during schema generation" warnings caused by missing ``self`` parameter | Low | 12/28/2018 |
| 1.12.0 | - **ADDED:** ``get_security_definitions`` and ``get_security_requirements`` hooks to ``OpenAPISchemaGenerator`` - **ADDED:** added ``get_summary_and_description`` and ``split_summary_from_description`` extension points to ``SwaggerAutoSchema`` to allow for better customisation - **IMPROVED:** updated ``swagger-ui`` to version 3.20.4 - **IMPROVED:** paginator ``next`` and ``previous`` fields are now marked as ``x-nullable`` (#263) - **IMPROVED:** added the ``tags`` argument to ``swagger_auto_ | Low | 12/24/2018 |
| 1.11.1 | - **IMPROVED:** updated ``swagger-ui`` to version 3.20.1 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.41 - **FIXED:** ``minLength`` and ``maxLength`` will now also work for ``ListSerializer`` in addition to ``ListField`` - **FIXED:** ``MultipleChoiceField`` will now use the ``multi`` ``collectionFormat`` where appropriate (#257) - **FIXED:** the ``format``, ``pattern``, ``enum``, ``min_length`` and ``max_length`` attributes of ``coreschema.Schema`` will now be persited into the c | Low | 11/29/2018 |
| 1.11.0 | - **ADDED:** ``PERSIST_AUTH``, ``REFETCH_SCHEMA_WITH_AUTH``, ``REFETCH_SCHEMA_ON_LOGOUT`` settings and related javascript implementation for persisting authentication data to swagger-ui localStorage - **IMPROVED:** UI-enabled views will now no longer generate the full specification document twice; the HTML part of the view will only generate a barebones ``Swagger`` object with no ``paths`` and ``definitions`` - **IMPROVED:** added the ``FETCH_SCHEMA_WITH_QUERY`` setting to enable fetching of t | Low | 10/14/2018 |
| 1.10.2 | - **ADDED:** added the ``DISPLAY_OPERATION_ID `` ``swagger-ui`` setting - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.38 - **IMPROVED:** Operation summary will now be parsed from multi-line view method docstrings (#205) - **IMPROVED:** ``pattern`` will now work on any field with a ``RegexValidator`` (would previously not appear on fields with special formats such as ``EmailField``) - **FIXED:** fixed an issue with ``RelatedFieldInspector`` handling of nested serializers - **FIXED | Low | 9/13/2018 |
| 1.10.1 | - **ADDED:** added the ``SPEC_URL`` setting for controlling the download link in ``swagger-ui`` and ``ReDoc`` - **ADDED:** updated ``ReDoc`` settings (added ``NATIVE_SCROLLBARS`` and ``REQUIRED_PROPS_FIRST``) - **ADDED:** added ``extra_styles`` and ``extra_scripts`` blocks to ui templates (#178) - **IMPROVED:** updated ``swagger-ui`` to version 3.18.2 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.37 - **FIXED:** stopped generating invalid OpenAPI by improper placement of ``readOn | Low | 9/9/2018 |
| 1.10.0 | - **ADDED:** added ``EXCLUDED_MEDIA_TYPES`` setting for controlling ``produces`` MIME type filtering (#158) - **ADDED:** added support for ``SerializerMethodField``, via the ``swagger_serializer_method`` decorator for the method field, and support for Python 3.5 style type hinting of the method field return type (#137, #175, #179) *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.SerializerMethodFieldInspector`` to your ``DEFAULT_FIELD_INSPECTORS`` array i | Low | 8/7/2018 |
| 1.9.2 | - **IMPROVED:** updated ``swagger-ui`` to version 3.17.6 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.32 - **IMPROVED:** added ``--api-version`` argument to the ``generate_swagger`` management command (#170) - **FIXED:** corrected various documentation typos (#160, #162, #171, #172) - **FIXED:** made ``generate_swagger`` work for projects without authentication (#161) - **FIXED:** fixed ``SafeText`` interaction with YAML codec (#159) | Low | 8/3/2018 |
| 1.9.1 | - **IMPROVED:** added a ``swagger_fake_view`` marker to more easily detect mock views in view methods; ``getattr(self, 'swagger_fake_view', False)`` inside a view method like ``get_serializer_class`` will tell you if the view instance is being used for swagger schema introspection (#154) - **IMPROVED:** updated ``swagger-ui`` to version 3.17.1 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.25 - **FIXED:** fixed wrong handling of duplicate urls in urlconf (#155) - **FIXED:** fixed c | Low | 6/29/2018 |
| 1.9.0 | *Release date: Jun 16, 2018* - **ADDED:** added ``DEFAULT_GENERATOR_CLASS`` setting and ``--generator-class`` argument to the ``generate_swagger`` management command (#140) - **FIXED:** fixed wrongly required ``'count'`` response field on ``CursorPagination`` (#141) - **FIXED:** fixed some cases where ``swagger_extra_fields`` would not be handlded (#142) - **FIXED:** fixed crash when encountering ``coreapi.Fields``s without a ``schema`` (#143) | Low | 6/29/2018 |
| 1.8.0 | - **ADDED:** added a :ref:`swagger_schema_fields <swagger_schema_fields>` field on serializer ``Meta`` classes for customizing schema generation (#132, #134) - **FIXED:** error responses from schema views are now rendered with ``JSONRenderer`` instead of throwing confusing errors (#130, #58) - **FIXED:** ``readOnly`` schema fields will now no longer be marked as ``required`` (#133) | Low | 5/30/2018 |
| 1.7.4 | *Release date: May 14, 2018* - **IMPROVED:** updated ``swagger-ui`` to version 3.14.2 - **IMPROVED:** updated ``ReDoc`` to version 2.0.0-alpha.20 - **FIXED:** ignore ``None`` return from ``get_operation`` to avoid empty ``Path`` objects in output - **FIXED:** request body is now allowed on ``DELETE`` endpoints (#118) | Low | 5/30/2018 |
| 1.7.3 | - **FIXED:** views whose ``__init__`` methods throw exceptions will now be ignored during endpoint enumeration | Low | 5/12/2018 |
| 1.7.2 | - **FIXED:** fixed generation of default ``SECURITY_REQUIREMENTS`` to match documented behaviour - **FIXED:** ordering of ``SECURITY_REQUIREMENTS`` and ``SECURITY_DEFINITIONS`` is now stable | Low | 5/12/2018 |
| 1.7.1 | - **IMPROVED:** updated ``swagger-ui`` to version 3.14.1 - **IMPROVED:** set ``swagger-ui`` ``showCommonExtensions`` to ``True`` by default and add ``SHOW_COMMON_EXTENSIONS`` setting key - **IMPROVED:** set ``min_length=1`` when ``allow_blank=False`` (#112, thanks to @elnappo) - **FIXED:** made documentation ordering of ``SwaggerDict`` extra attributes stable | Low | 5/5/2018 |
| 1.7.0 | - **ADDED:** added integration with [djangorestframework-recursive](https://github.com/heywbj/django-rest-framework-recursive) (#109, #110, thanks to @rsichny) *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.RecursiveFieldInspector`` to your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value - **FIXED:** ``SchemaRef`` now supports cyclical references via the ``ignore_unresolved`` argument | Low | 4/26/2018 |
| 1.6.2 | - **IMPROVED:** updated ``swagger-ui`` to version 3.13.6 - **IMPROVED:** switched ``ReDoc`` to version 2.0.0-alpha.17 (was 1.21.2); fixes #107 - **FIXED:** made documentation ordering of parameters stable for urls with multiple parameters (#105, #106) - **FIXED:** fixed crash when using a model ``ChoiceField`` of unknown child type | Low | 4/25/2018 |
| 1.6.1 | - **ADDED:** added ``SUPPORTED_SUBMIT_METHODS`` ``swagger-ui`` setting | Low | 4/1/2018 |
| 1.6.0 | - **IMPROVED:** ``OAUTH2_REDIRECT_URL`` will now default to the built in ``oauth2-redirect.html`` file | Low | 4/1/2018 |
| 1.5.1 | - **IMPROVED:** updated ``swagger-ui`` to version 3.13.0 - **FIXED:** fixed a crash caused by ``serializers.OneToOneRel`` (#81, thanks to @ko-pp) | Low | 3/18/2018 |
| 1.5.0 | - **IMPROVED:** ``serializers.HiddenField`` are now hidden (#78, #79, thanks to @therefromhere) *NOTE:* in order for this to work, you will have to add the new ``drf_yasg.inspectors.HiddenFieldInspector`` to your ``DEFAULT_FIELD_INSPECTORS`` array if you changed it from the default value - **IMPROVED:** type of model field is now detected for ``serializers.SlugRelatedField`` with ``read_only=True`` (#82, #83, thanks to @therefromhere) | Low | 3/12/2018 |
| 1.4.7 | - **FIXED:** prevent crashes caused by attempting to delete object attributes which do not exist in the first place (#76) | Low | 3/5/2018 |
| 1.4.6 | - **IMPROVED:** updated ``swagger-ui`` to version 3.12.0 - **IMPROVED:** updated ``ReDoc`` to version 1.21.2 | Low | 3/5/2018 |
| 1.4.5 | - **FIXED:** fixed an issue with modification of ``swagger_auto_schema`` arguments in-place during introspection, which would sometimes cause an incomplete Swagger document to be generated after the first pass (#74, #75) | Low | 3/5/2018 |
| 1.4.4 | - **IMPROVED:** ``type`` for ``ChoiceField`` generated by a ``ModelSerializer`` from a model field with ``choices=...`` will now be set according to the associated model field (#69) - **FIXED:** ``lookup_field`` and ``lookup_value_regex`` on the same ``ViewSet`` will no longer trigger an (#68) | Low | 2/27/2018 |