Генерация документации для существующих эндпоинтов

Будем честны: если бы не инструменты автоматической генерации, разработчики, возможно, никогда бы не документировали свои API. Ведь кто захочет писать документацию вручную, если можно потратить это время на рефакторинг... или добавление новых багов!

Давайте разбираться, как drf-yasg делает всю магию документирования за вас. Мы углубимся в автоматическую генерацию документации, просмотрим, как настраивать отображение эндпоинтов и как поддерживать несколько версий API.

🔧 Как работает автоматическая генерация документации?

drf-yasg использует спецификацию OpenAPI (ранее известную как Swagger), чтобы "читать" ваши маршруты (URLs) и автоматически извлекать информацию о каждом эндпоинте, включая:

• HTTP-методы (GET, POST, PUT, DELETE и т.д.),
• параметры маршрутов,
• данные запросов и ответов,
• сериализаторы и схемы данных.

Это значит, что вам остается только описать структуры данных и назначение эндпоинтов, а всё остальное сделает за вас drf-yasg.

🏗️ Практическое создание автоматической документации

Предположим, у нас есть приложение blog с базовыми CRUD-операциями для статей. Вот маршруты нашего API:

from django.urls import path
from blog import views

urlpatterns = [
    path('articles/', views.ArticleList.as_view(), name='article-list'),
    path('articles/<int:pk>/', views.ArticleDetail.as_view(), name='article-detail'),
]

Шаг 1: Автоматическая генерация документации

Мы уже настроили drf-yasg на предыдущей лекции. Теперь добавим эндпоинты для Swagger UI и схемы документации OpenAPI.

Откройте urls.py вашего проекта и добавьте следующие строки:

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Blog API",
        default_version='v1',
        description="Документационная страница для API блога",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="support@blogapi.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    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'),
    path('swagger.json', schema_view.without_ui(cache_timeout=0), name='schema-json'),
]

Теперь перейдите в браузере по адресу:
http://127.0.0.1:8000/swagger/
и вы увидите автоматически сгенерированную документацию для ваших эндпоинтов!

Шаг 2: Как это выглядит?

В Swagger UI вы увидите:

• Список всех маршрутов, предоставленных вашим проектом.
• Схему запросов и ответов.
• Возможность тестировать эндпоинты прямо из интерфейса. Это особенно полезно, если вам нужно проверить ваш API без использования стороннего инструмента вроде Postman.

Попробуйте открыть маршрут /articles/, нажмите "Try it out", отправьте запрос и получите список статей (или пустой массив, если данных ещё нет).

🛠️ Настройка отображения эндпоинтов

Иногда документация получается слишком обширной, и вам нужно структурировать её более логично. Например, вы можете сгруппировать эндпоинты по приложениям или версиям API.

Группировка эндпоинтов

Для группировки используются "декораторы схем". Это просто! Вот пример для нашего приложения blog:

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

class ArticleList(APIView):
    @swagger_auto_schema(
        operation_description="Получение списка всех статей",
        responses={200: "Список статей или пустой массив"},
    )
    def get(self, request):
        # Здесь логика вашего метода.
        return Response([], status=status.HTTP_200_OK)

Декоратор swagger_auto_schema позволяет добавить уникальное описание и примеры ответа для маршрута GET /articles/.

Версионирование API

Вы можете поддерживать документацию для нескольких версий API (например, 1.0 и 2.0). Вот пример:

schema_view_v1 = get_schema_view(
    openapi.Info(
        title="Blog API v1",
        default_version='v1',
        description="Документация для первой версии API",
    ),
    public=True,
)

schema_view_v2 = get_schema_view(
    openapi.Info(
        title="Blog API v2",
        default_version='v2',
        description="Документация для второй версии API, с новыми фичами",
    ),
    public=True,
)

urlpatterns = [
    path('swagger/v1/', schema_view_v1.with_ui('swagger', cache_timeout=0), name='swagger-v1'),
    path('swagger/v2/', schema_view_v2.with_ui('swagger', cache_timeout=0), name='swagger-v2'),
]

Теперь вы можете открывать документацию отдельно для каждой версии, что очень удобно в больших проектах.

⭐ Подсказки и хорошая практика

• Описание каждого эндпоинта: используйте swagger_auto_schema или дополнительные аннотации, чтобы пояснить, зачем нужен эндпоинт и какие данные он возвращает.

• Актуальность документации: не забывайте регулярно проверять документацию после внесения изменений в API! Никакой инструмент не спасёт вас, если вы добавили новый эндпоинт и забыли его задокументировать.

• Примеры запросов и ответов: добавляйте примерные данные к эндпоинтам, чтобы коллеги-разработчики знали, чего ожидать.

Сегодня вы узнали, как легко автоматизировать процесс документирования API с помощью drf-yasg. Правда, приятно, когда за вас всё делает машина? Но не забывайте, что полная и акутальная документация — это ваша ответственность. Теперь вы можете гордо показывать свой Swagger UI коллегам (и на собеседованиях тоже).

На следующем занятии мы разберем, как тестировать API через Swagger UI и Redoc.

1

Задача

Модуль 3: Django, 23 уровень, 2 лекция

Недоступна

Установка и базовая настройка drf-yasg

Установка и базовая настройка drf-yasg

Открыть

1

Задача

Модуль 3: Django, 23 уровень, 2 лекция

Недоступна

Генерация документации для эндпоинтов ViewSet

Генерация документации для эндпоинтов ViewSet

Открыть