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