Swagger для Django Rest Framework

Зачем нам нужно документировать API ? Что за такие страшные слова Swagger и OpenAPI ? Каквя между ними разница? Как легко подключить Swagger документацию вашим эндпоинтам , реализванные на DRF? Все в этой статье

OpenAPI - это официальное название спецификации . Разработкой спецификации занимается больше 30 компаний, включая Microsoft, Google, IBM и другие.

Swagger - это инструменты для реализации OpenAPI спецификации.Набор инструментов Swagger включает в себя набор открытых, бесплатных и коммерческих инструментов, которые можно использовать на разных этапах жизненного цикла API.

Swagger UI - это коллекция Html, js css документов , которые генерируют прекрасную документацию.

Для Django Rest Framework мы будем использовать библиотеку drf-yasg

Установливаем drf-yasg

pip install -U drf-yasg

В файле settings.py подключаем drf_yasg.

INSTALLED_APPS = [
   ...
   'django.contrib.staticfiles',  #Необходим для  swagger ui's css/js файлов (По умолчанию включен)
   'drf_yasg',
   ...
]

Затем в файле urls.py.

from rest_framework import permissions
from django.urls import path, include, re_path
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 = [
    ...
    re_path(r'^swagger(?P\.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'),
   ...
]

В комплекте последняя версия Swagger Ui и Redoc

Сгенерированная схема Swagger может быть автоматически проверена с помощью swagger-spec-validator

Swagger-spec-validator - это библиотека Python, которая проверяет спецификации Swagger на соответствие спецификации Swagger 1.2 или Swagger 2.0. Валидатор стремится проверить на полное соответствие Спецификации.