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: