Swagger для Django REST Framework

14 Ноя 2019 , 1648

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

comments powered by Disqus

Подписка

Подпишитесь на наш список рассылки, чтобы получать обновления из блога

Рубрики

Теги