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=