Swagger для Django REST Framework

Зачем нам нужно документировать API ?
Что за такие страшные слова Swagger и OpenAPI ? Какая между ними разница?
Как легко подключить Swagger документацию к вашим эндпоинтам(endpoints) , реализованных с помощью Django REST Framework(DRF)?
Попробуем об этом разобраться в этой  статье.

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

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

Перечислим некоторые инструменты Swagger:

1. Swagger UI - это коллекция HTML, javascript , CSS документов, которая генерирует прекрасную документацию.

2. Swagger Codegen - это инструмент, который генерирует клиентский код, серверный код и документацию на основе OpenAPI спецификации.

Для Django REST Framework мы рассмотрим две замечательные библиотеки:

drf-yasg - которая очень популярна , но в ней используется спецификация OpenAPI 2.0. Эту библиотеку нецелесообразно использовать для новых проектов , так как там нет поддержки OpenAPI 3.0 и выше. Даже сами разработчики этой библиотеки советуют обратить внимание на drf-spectacular для новых проектов, где нужна поддержка OpenAPI 3.0

drf-spectacular - относительно новая библиотека , которая набирает популярность и которая поддерживает спецификацию OpenAPI 3

Поочередно рассмотрим использование обеих библиотек. До подключения мы создадим простое приложение на Django, где создадим модель Post(Статья) и реализуем API с помощью DRF. Исходный код лежит на Github.

Подключение drf-yasg

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

pip install -U drf-yasg

Тут важно учесть , что на данный момент эта библиотека официально не поддерживает Django 5 и выше и поэтому мы будем использовать Django 4.1

В файле 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

Переходя по адресу http://127.0.0.1:8000/swagger/ мы увидим сгенерированную документацию

Подключение drf-spectacular

Тут мы можем смело использовать последную версию Django. На сегодняшний день это Django 5. При установке библиотеки drf-spectacular мы зафиксируем используемую версию , так как сами разработчики данной библиотеки предупреждают , что при обновлении версии может что-то сломаться

Устанавливаем актуальную версию drf-spectacular

pip install drf-spectacular==0.27.0

В файле settings.py

INSTALLED_APPS = [
    .....
    'drf_spectacular',
]

REST_FRAMEWORK = {
    ....
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'Django5 Test Swagger API',
    'DESCRIPTION': 'Django5 Test Swagger API description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    # OTHER SETTINGS
}

В файле urls.py

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
    SpectacularRedocView
)

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI:
    path(
        'api/schema/swagger-ui/',
        SpectacularSwaggerView.as_view(url_name='schema'),
        name='swagger-ui'
    ),
    path(
        'api/schema/redoc/',
        SpectacularRedocView.as_view(url_name='schema'),
        name='redoc'
    ),
]

Исходный код лежит на Github

Заключение

В данной статье мы рассмотрели две библиотеки для Django Rest Framework (drf) , которые предназначены для работы с OpenApi и для генерации документации. Если вы хотите использовать OpenApi 3.0 и выше , то я настоятельно рекомендую использовать drf-spectacular , а если у вас легаси код и нужно использовать OpenApi 2.0 или ниже , то лучше использовать drf-yasg