Swagger для Django Rest Framework

14 Ноя 2019 , 814

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

comments powered by Disqus

Подписка

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

Рубрики

Теги