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 спецификации(OpenAPI Specification ).Набор инструментов Swagger включает в себя набор открытых, бесплатных и коммерческих инструментов, которые можно использовать на разных этапах жизненного цикла API.

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

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

drf-yasg - которая очень популярна , но в ней используется спецификация OpenAPI 2.0

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

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

Давайте перейдем по адресу http://127.0.0.1:8000/swagger/ и увидим:

Тут у нас есть отображается та информация, которую мы определили в этом коде:

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,),
)

Давайте добавим модели и сделаем API и посмотрим как все это будет отображаться в swagger. Для примера создадим модель статей Post и помощью drf реализуем

Создадим приложение posts

python manage.py startapp posts

В файле models.py создадим модель Post

from django.db import models
from django.utils import timezone


class Post(models.Model):
    title = models.CharField(max_length=255)
    content = models.TextField()
    created_at = models.DateTimeField(default=timezone.now)

    def __str__(self):
        return self.title

    class Meta:
        verbose_name = 'Статья'
        verbose_name_plural = 'Статьи'

Создадим сериалайзер в файле serializers.py

from rest_framework import serializers
from posts.models import Post


class PostSerializer(serializers.ModelSerializer):
    class Meta:
        model = Post
        fields = ('title', 'content', 'created_at')

В файле posts/views.py создадим viewset

from rest_framework import viewsets
from rest_framework import permissions
from posts.models import Post
from posts.serializers import PostSerializer


class PostViewSet(viewsets.ModelViewSet):
    """
    API endpoint for posts
    """
    queryset = Post.objects.all()
    serializer_class = PostSerializer

Теперь если мы перейдем по адресу , то увидим сгенерировнную документацию для Posts

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

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