Практическое занятие по документированию API

Сегодня наша задача — объединить всё изученное и на практике создать хорошо организованную документацию для собственного API. Готовы? Погнали!

К концу занятия у нас будет:

1. Полноценная автодокументация для созданного Django REST API.
2. Кастомизированные описания эндпоинтов.
3. Примеры запросов и ответов.
4. Документация, доступная как через Swagger UI, так и через Redoc.

Примечание: Мы будем документировать API для нашего учебного проекта — блога с моделью Post (созданной на прошлых занятиях).

🛠 Шаг 1: установка и настройка Swagger (drf-yasg)

Если вы еще не установили drf-yasg, сделайте это сейчас. В вашем виртуальном окружении выполните команду:

pip install drf-yasg

Добавьте drf_yasg в список приложений в INSTALLED_APPS файла settings.py:

INSTALLED_APPS = [
    ...
    'drf_yasg',
]

Настройка URL для Swagger UI

Добавим маршруты для доступа к документации. В файле urls.py проекта:

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from django.urls import path

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="admin@example.com"),
        license=openapi.License(name="MIT 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'),
]

Теперь по адресам:

• /swagger/ доступна Swagger документация.
• /redoc/ доступна Redoc документация.

Перезапустите сервер. Откройте браузер и убедитесь, что документация работает.

📝 Шаг 2: генерация документации для существующих эндпоинтов

Наш API уже имеет несколько эндпоинтов для модели Post:

• Список постов (GET /api/posts/)
• Детали поста (GET /api/posts/<id>/)
• Создание поста (POST /api/posts/)
• Обновление поста (PUT /api/posts/<id>/)
• Удаление поста (DELETE /api/posts/<id>/)

Описание эндпоинтов

Для каждого из ваших эндпоинтов вы можете добавить кастомные описания и примеры запросов/ответов. В views.py определим их, используя декораторы drf-yasg:

from rest_framework.decorators import api_view
from rest_framework.response import Response
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
from .models import Post
from .serializers import PostSerializer

@swagger_auto_schema(
    method='get',
    operation_description="Получить список всех постов",
    responses={200: PostSerializer(many=True)},
    tags=['Посты']
)
@api_view(['GET'])
def post_list(request):
    posts = Post.objects.all()
    serializer = PostSerializer(posts, many=True)
    return Response(serializer.data)

@swagger_auto_schema(
    method='post',
    operation_description="Создать новый пост",
    request_body=PostSerializer,
    responses={201: PostSerializer},
    tags=['Посты']
)
@api_view(['POST'])
def create_post(request):
    serializer = PostSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=201)
    return Response(serializer.errors, status=400)

Теперь, посетив /swagger/, вы увидите подробные описания для эндпоинтов.

🎨 Шаг 3: добавление примеров

Мы можем добавить примеры запросов через OpenAPI параметры. Например, для создания поста:

example_data = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'title': openapi.Schema(type=openapi.TYPE_STRING, description='Заголовок поста'),
        'content': openapi.Schema(type=openapi.TYPE_STRING, description='Содержимое поста')
    },
    required=['title', 'content']
)

@swagger_auto_schema(
    method='post',
    request_body=example_data,
    responses={201: PostSerializer},
    tags=['Посты']
)
@api_view(['POST'])
def create_post(request):
    ...

Swagger UI теперь будет показывать пример JSON для POST запроса прямо в интерфейсе.

📂 Шаг 4: кастомизация отображения

Группировка эндпоинтов. Для этого мы используем tags. Для всех представлений указывайте тематические теги, чтобы эндпоинты отображались в группах. Например, tags=['Посты'].

Описание параметров. Если эндпоинт принимает параметры, вы можете задать их явно:

id_param = openapi.Parameter(
    'id', openapi.IN_PATH, description="ID поста", type=openapi.TYPE_INTEGER
)

@swagger_auto_schema(
    method='get',
    manual_parameters=[id_param],
    responses={200: PostSerializer},
    tags=['Посты']
)
@api_view(['GET'])
def post_detail(request, id):
    ...

🔍 Шаг 5: тестирование через Swagger UI и Redoc

Откройте /swagger/. Попробуйте протестировать эндпоинты:

• Отправьте POST запрос с примером JSON.
• Убедитесь, что запросы GET, PUT, DELETE работают.

Теперь проверьте /redoc/. Убедитесь, что документация аккуратно отображается.

🛡 Шаг 6: поддержание актуальности

Для поддержки документации в актуальном состоянии настраивают автоматическое обновление. Например:

• При помощи GitHub Actions вы можете генерировать Swagger файл (JSON) и деплоить его на внешний ресурс.
• Инструменты, такие как SwaggerHub, могут быть полезны.

🎯 Итоговое задание для вас

1. Добавьте документацию для всех существующих эндпоинтов вашего API.
2. Кастомизируйте документацию: добавьте описания, примеры, параметры.
3. Попробуйте протестировать свой API через Swagger и Redoc.

Документация — это ваше зеркало. Чем лучше она выглядит, тем проще вашим коллегам (и вам самим через 6 месяцев) разобраться в API.

1

Задача

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

Недоступна

Создание аннотации документации для эндпоинтов

Создание аннотации документации для эндпоинтов

Открыть

1

Задача

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

Недоступна

Улучшение документации для эндпоинта

Улучшение документации для эндпоинта

Открыть

3

Опрос

Настройка Redoc для проекта, 23 уровень, 9 лекция

Недоступен

Настройка Redoc для проекта

Настройка Redoc для проекта

Открыть