Кастомизация Swagger документации

Swagger-сетап — это как базовый шаблон веб-сайта. Работает? Да. Выглядит нормально? Похоже на то. Но вы ведь хотите чего-то большего, чтобы документация выглядела профессионально, соответствовала айдентике вашего проекта и давала максимум информации пользователю. С помощью правильной кастомизации вы сможете:

1. Упростить жизнь разработчикам, добавив описания и примеры.
2. Увеличить доверие пользователей, применяя логотипы и цвета бренда.
3. Сделать документацию более интуитивно понятной.

Настройка внешнего вида Swagger-документации

Swagger UI позволяет добавить свой логотип и изменить цветовую палитру. Это делается в параметрах настройки Swagger-объекта. Откройте ваш проект, найдите конфигурацию для drf-yasg и отредактируйте её.

Вот пример стандартной настройки для Swagger:

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Мой API",
        default_version='v1',
        description="Документация для API",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="support@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
)

Для кастомизации добавим пару дополнительных параметров:

schema_view = get_schema_view(
    openapi.Info(
        title="🚀 API моего проекта",
        default_version='v1',
        description="Подробная документация для разработчиков",
        terms_of_service="https://example.com/terms/",
        contact=openapi.Contact(email="admin@myapi.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
    urlconf='myproject.urls',
)

# Установка логотипа и цветов
swagger_settings = {
    'DEFAULT_MODEL_RENDERING': 'example',
    'LOGO_URL': 'https://example.com/static/logo.png',  # Ваш логотип
    'VALIDATOR_URL': None,
    'USE_SESSION_AUTH': False,
}

Теперь в интерфейсе Swagger UI будет аккуратно отображаться ваш логотип и "брендовая" информация. Глянец? Да!

Добавление кастомных описаний и примеров

Иногда базовая автоматическая генерация документации недостаточна. Чтобы добавить дополнительные описания, можно использовать Swagger-декораторы. Например, вы хотите описать работу конкретного эндпоинта.

Пример с кастомным описанием эндпоинта

Откроем наш views.py:

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

class MyAPIView(APIView):
    @swagger_auto_schema(
        operation_summary="Получение списка объектов",
        operation_description="Этот эндпоинт возвращает полный список объектов модели",
        responses={
            200: openapi.Response(
                description="Успешный ответ",
                examples={
                    "application/json": [
                        {"id": 1, "name": "Object A"},
                        {"id": 2, "name": "Object B"}
                    ]
                }
            ),
            404: "Не найдено"
        }
    )
    def get(self, request):
        return Response([{"id": 1, "name": "Object A"}, {"id": 2, "name": "Object B"}])

Здесь мы:

1. Добавили operation_summary — краткое описание функции.
2. Использовали operation_description для детального объяснения.
3. Указали возможные типы ответов (включая пример).

Если вы зайдёте в Swagger UI, то увидите, как ваш API внезапно стал удобным и дружелюбным к новичкам.

Улучшение читаемости и структуры документации

Swagger позволяет группировать эндпоинты в категории. Например, в большом проекте логичным будет разделить API на модули: "Пользователи", "Товары", "Заказы" и так далее. Это делается с помощью параметра tags.

Давайте рассмотрим пример:

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    tags=["Пользователи"],
    operation_summary="Создание нового пользователя",
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'username': openapi.Schema(type=openapi.TYPE_STRING, description="Имя пользователя"),
            'email': openapi.Schema(type=openapi.TYPE_STRING, description="Email пользователя"),
            'password': openapi.Schema(type=openapi.TYPE_STRING, description="Пароль"),
        },
        required=['username', 'email', 'password'],
    ),
    responses={201: "Успешное создание"}
)
def create_user(request):
    pass  # Имплементация логики

После добавления tags все эндпоинты, относящиеся к "Пользователям", будут аккуратно сгруппированы в Swagger UI.

Добавление кастомных схем через аннотации

Иногда возникает необходимость полностью переопределить структуру документации для определённого эндпоинта. Вот пример сложной валидации входящих данных:

from drf_yasg import openapi

@swagger_auto_schema(
    operation_description="Создание заказа",
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'product_id': openapi.Schema(type=openapi.TYPE_INTEGER, description="ID продукта"),
            'count': openapi.Schema(type=openapi.TYPE_INTEGER, description="Количество товара"),
        },
        required=['product_id', 'count']
    ),
    responses={
        201: openapi.Response("Заказ создан"),
        400: "Неверный запрос"
    }
)
def create_order(request):
    pass  # Логика обработки запроса

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

Работа с версионностью API

Ваш API может развиваться, а это значит, что старые версии эндпоинтов могут поддерживаться параллельно с новыми. Например, для версии "v2" API можно создать кастомизированные схемы:

schema_view_v2 = get_schema_view(
    openapi.Info(
        title="🚀 API v2",
        version="v2",
        description="Документация для версии 2",
    ),
    public=True,
)

И не забудьте добавить отдельные маршруты для каждой версии!

from django.urls import path

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

Теперь ваши пользователи смогут переключаться между версиями API, как профи.

Часто встречающиеся ошибки

Когда вы начинаете кастомизировать Swagger, легко запутаться. Например, вы можете забыть указать обязательные поля в объекте схемы. Это приведёт к ошибкам в генерации документации. Ещё один популярный косяк — использование одного и того же тега tags для разных категорий, что заставляет Swagger UI путаться. Также не забывайте, что примеры ответов (если они указаны) должны соответствовать вашим сериализаторам.

Практическое применение

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

Swagger-документация также часто используется на собеседованиях для демонстрации вашего уровня. Укажите в резюме, что на вашем последнем проекте документация была кастомизирована под бренд компании, и вы наверняка получите дополнительные баллы!

1

Задача

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

Недоступна

Подключение кастомного CSS к Swagger UI

Подключение кастомного CSS к Swagger UI

Открыть

3

Опрос

Введение в документирование API, 23 уровень, 4 лекция

Недоступен

Введение в документирование API

Введение в документирование API

Открыть