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

Давайте перейдем по адресу 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. Валидатор стремится проверить на полное соответствие Спецификации.