JoelLefkowitz / drf-yasg

Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.
https://drf-yasg2.readthedocs.io/en/stable/
BSD 3-Clause "New" or "Revised" License
65 stars 2 forks source link

DRF - Yet another Swagger generator 2

Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

Notice

The original drf-yasg repository is now maintained again. This repo will be left as is to serve those still using it.

Please migrate back to the using the origional repository and for submitting contributions.

Status

Source Shields
Project release build
Publishers pypi
Downloads pypi_downloads
Raised issues pulls

Compatibility

Release Python Django Django REST Framework
1.18.x 2.7 1.11 3.8 - 3.9
1.18.x 3.6 - 3.8 2.2 - 3.0 3.8 - 3.12
1.19.x 3.6 - 3.9 2.2 - 3.1 3.8 - 3.12

Features

Screenshots

Fully nested request and response schemas

Redoc screenshot

Choose between redoc and swagger-ui

Swagger-ui screenshot

Model definitions

Models screenshot

Installing

Installing the package from pypi:

pip install drf-yasg2

Given the numerous methods to manually customize the generated schema, it makes sense to validate the result to ensure it still conforms to OpenAPI 2.0. To this end, validation is provided at the generation point using Python Swagger libraries, and can be activated by passing validators=['ssv'] to get_schema_view; if the generated schema is not valid, a SwaggerValidationError is raised by the handling codec.

To provide the built-in validation mechanisms you can install the extra requirements:

pip install drf-yasg2[validation]

Usage

Checkout the live demo!

Add the package to INSTALLED_APPS:


   INSTALLED_APPS = [
      ...
      'drf_yasg2',
      ...
   ]

Add the endpoints to urlpatterns:


   from django.urls import path, re_path
   from rest_framework import permissions
   from drf_yasg2.views import get_schema_view
   from drf_yasg2 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 = [
      re_path(r'^swagger(?P<format>\.json|\.yaml)$', 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='schema-redoc'),
      ...
   ]

This exposes 4 endpoints:

Docs

Additional details are available in the full documentation and the changelog.

To generate the documentation locally:

scripts/docs.sh

Tests

To run tests:

tox

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

Versioning

SemVer is used for versioning. For a list of versions available, see the tags on this repository.

Authors

This project forked from drf-yasg. Credit is given to Cristi Vîjdea and the original contributors.

Huge thank you to the contributors who've participated in this project. Have a look at the contributions!

License

This project is licensed under the BSD 3-Clause License - see the LICENSE.md file for details