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

Будемо чесними: якби не інструменти автоматичної генерації, розробники, можливо, ніколи б не документували свої 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.