Схемы и документация

Зачем документация API

API пользуются другие разработчики: фронтендеры, авторы мобильных приложений, партнёры. Им нужно знать, какие есть адреса, какие параметры принимаются, что вернётся и какие бывают ошибки. Поддерживать такую документацию вручную тяжело — она устаревает. Решение — генерировать её из кода.

OpenAPI

OpenAPI (бывший Swagger) — стандарт описания REST API в YAML/JSON:

paths:
  /api/posts/:
    get:
      summary: Список постов
      parameters:
        - name: page
          in: query
          schema: {type: integer}
      responses:
        "200":
          description: OK

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

drf-spectacular

Самый популярный генератор OpenAPI 3 для DRF:

pip install drf-spectacular

INSTALLED_APPS += ["drf_spectacular"]

REST_FRAMEWORK = {
    ...
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "API блога",
    "DESCRIPTION": "Посты, комментарии и теги",
    "VERSION": "1.0.0",
}

Маршруты:

from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
    path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
    path("api/redoc/", SpectacularRedocView.as_view(url_name="schema"), name="redoc"),
]

• /api/schema/ — сама схема (YAML);
• /api/docs/ — Swagger UI: интерактивная документация с кнопкой «Try it out»;
• /api/redoc/ — ReDoc: красивая документация для чтения.

Схему можно сохранить в файл: python manage.py spectacular --file schema.yml.

Что генерируется автоматически

drf-spectacular анализирует ваши ViewSet, сериализаторы, фильтры, пагинацию и права:

• endpoints и методы — из роутера и классов;
• поля запросов и ответов — из сериализаторов (типы, обязательность, read_only);
• параметры — из filterset_fields, search_fields, ordering_fields, пагинации;
• требования аутентификации — из authentication_classes.

Уточнение схемы: extend_schema

То, что нельзя вывести из кода автоматически, описывают декоратором:

from drf_spectacular.utils import OpenApiParameter, extend_schema, extend_schema_view


@extend_schema_view(
    list=extend_schema(summary="Список опубликованных постов"),
    retrieve=extend_schema(summary="Пост по id"),
)
class PostViewSet(viewsets.ModelViewSet):
    ...

    @extend_schema(
        summary="Опубликовать пост",
        request=None,
        responses={200: {"type": "object", "properties": {"status": {"type": "string"}}}},
    )
    @action(detail=True, methods=["post"])
    def publish(self, request, pk=None):
        ...

Для SerializerMethodField укажите тип через @extend_schema_field(OpenApiTypes.INT), иначе в схеме будет «строка».

Документируйте код

Docstring класса и методов попадают в описание endpoints:

class PostViewSet(viewsets.ModelViewSet):
    """Посты блога. Читать могут все, создавать — вошедшие, изменять — только автор."""

Итог

• OpenAPI — стандарт описания API, по нему строится интерактивная документация.
• drf-spectacular: DEFAULT_SCHEMA_CLASS, маршруты схемы, Swagger UI и ReDoc.
• Большая часть схемы генерируется из сериализаторов, ViewSet и фильтров.
• extend_schema дописывает то, что нельзя вывести автоматически.