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

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

До кінця заняття у нас буде:

1. Повноцінна автодокументація для створеного Django REST API.
2. Кастомізовані описи endpoint'ів.
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.

3

Опитування

Налаштування Redoc для проєкту, рівень 23, лекція 9

Недоступний

Налаштування Redoc для проєкту

Налаштування Redoc для проєкту

Відкрити