Swagger-сетап — це як базовий шаблон веб-сайту. Працює? Так. Виглядає нормально? Схоже на те. Але ж ти хочеш чогось більшого, щоб документація виглядала професійно, відповідала айдентиці твого проєкту і давала максимум інформації користувачу. З правильною кастомізацією ти зможеш:
- Спростити життя розробникам, додавши описи та приклади.
- Збільшити довіру користувачів, використовуючи логотипи та кольори бренду.
- Зробити документацію більш інтуїтивно зрозумілою.
Налаштування зовнішнього вигляду 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"}])Тут ми:
- Додали
operation_summary— короткий опис функції. - Використали
operation_descriptionдля детального пояснення. - Вказали можливі типи відповідей (включаючи приклад).
Якщо ви зайдете в 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-документація також часто використовується на співбесідах для демонстрації твого рівня. Зазнач у резюме, що на твоєму останньому проєкті документація була кастомізована під бренд компанії, і ти точно отримаєш додаткові бали!
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ