Вступ до документування API

Сьогодні наша ціль — зрозуміти, навіщо документувати API, які для цього існують інструменти, і як підтримка документації спрощує життя всім: тобі, твоїм колегам і навіть твоєму майбутньому "я" (наприклад, через 6 місяців, коли ти повернешся до проєкту і спробуєш згадати, що ти там писав).

Чому важливо документувати API?

Кожен програміст пам'ятає ті жорсткі моменти, коли він намагався розібратися в API іншого розробника без документації. Це схоже на спробу зрозуміти серіал з середини третього сезону. Спойлер: це не весело.

Уявіть, що ви потрапляєте в бібліотеку, де книги лежать безладно, без назв і описів. Звісно, вам не захочеться працювати в такому хаосі. Аналогічно, ваш API без документації нічим не відрізняється від цієї неорганізованої бібліотеки.

А ось документований код! Ось його переваги:

1. Читабельність і зрозумілість не тільки для інших, але й для вас. Через кілька місяців ви самі можете забути, чому ендпоінт /get_data приймає 5 параметрів і що він взагалі повертає.
2. Швидке підключення нових розробників: якщо ви працюєте в команді, документація допомагає новим колегам швидше влитися в проєкт.
3. Автоматизація тестування: багато інструментів тестування, такі як Swagger UI, дозволяють взаємодіяти з API через інтерфейс на основі вашої документації.
4. Краща підтримка API: сумісність між версіями (Backward Compatibility) легше підтримувати, якщо всі зміни документовані.
5. Співбесіди та відкриті проєкти: якщо ви представите свій API на співбесіді або у відкритому проєкті, то добре оформлена документація викличе симпатію.

Як ми документуємо API?

Отже, як зробити так, щоб ваш API "заговорив"? Для цього існують інструменти та стандарти. Зокрема, для Django REST Framework ми будемо використовувати Swagger (через бібліотеку drf-yasg) та Redoc.

1. Swagger:

   • Swagger — це популярний фреймворк для документування RESTful API.
   • Цей інструмент надає зрозумілий інтерфейс з автоматичною генерацією документації та можливістю тестування ендпоінтів.

2. Redoc:

   • Більш сучасний інструмент для документування, який має красивий інтерфейс та відмінну підтримку специфікацій OpenAPI.
   • Підходить для більш складних та довготривалих проєктів.

3. PyDoc (для Python-коду):

   • PyDoc в основному використовується для документування функцій, класів та методів у Python. Це корисно, якщо ви хочете надати опис логіки вашого коду, але не самого API.

4. Специфікація OpenAPI (раніше Swagger 2.0):

   • Це стандарт, який визначає, як повинна виглядати структура документування API.

Наш сьогоднішній вибір — Swagger. Ми будемо використовувати бібліотеку drf-yasg, щоб підключити автоматичну генерацію документації для вашого Django REST API.

Чому саме Swagger і drf-yasg?

Swagger став стандартом де-факто для документування RESTful API. Багато розробників очікують побачити документацію у форматі Swagger, коли вони працюють з API.

Основні переваги drf-yasg:

1. Автоматизація: drf-yasg легко інтегрується з вашим проєктом на Django REST Framework і може автоматично збирати дані про ваші ендпоінти.
2. Зручність тестування: це не просто документація, але й інструмент для відправки запитів і аналізу відповідей.
3. Гнучкість: бібліотека підтримує кастомізацію і дозволяє додавати необхідні описи, приклади та анотації.

Типова структура Swagger-документації

• Опис ендпоінтів: наприклад, GET /api/users/ для отримання списку всіх користувачів.
• Параметри: які параметри приймає ендпоінт (наприклад, id або page).
• Тіла запитів і відповідей: які дані очікуються у POST або PUT запитах і що повертається у відповіді.
• Коди станів HTTP: вказує, що означає кожен стан відповіді (наприклад, 200 OK або 404 Not Found).

Як виглядає процес документування?

Ось приклад невеликого сценарію документування API. Ви вже маєте уявлення про те, як організовані ваші маршрути та представлення (views).

У вас є ендпоінт для отримання списку книг.

# views.py
from rest_framework.response import Response
from rest_framework.views import APIView

class BookListView(APIView):
    """
    get:
    Повертає список усіх книг.
    """
    def get(self, request):
        books = [{"id": 1, "title": "Django for Beginners"}, {"id": 2, "title": "Two Scoops of Django"}]
        return Response({"books": books})

Часто такі описи документації (наприклад, рядок Повертає список усіх книг.) стають частиною Swagger-документації. Уся магія починається, коли ми підключаємо drf-yasg і балансуємо між автоматикою та ручним налаштуванням.

Реальне застосування: як Swagger допомагає в роботі

Зі Swagger UI ти і твоя команда можете:

1. Переглядати всі ендпоінти API та їх параметри в одному місці.
2. Тестувати ендпоінти прямо в браузері, без необхідності писати окремий клієнтський код для відправки HTTP-запитів.
3. Автоматично оновлювати документацію при зміні ендпоінтів.

Swagger стає твоїм єдиним джерелом "правди" про те, як працює API.

Зворотні посилання та ресурси

• Документація drf-yasg — це офіційний гайд по бібліотеці, який стане в нагоді для налаштування.
• Документація OpenAPI — якщо хочеш зануритися в деталі стандартів.
• Redoc — альтернатива для тих, хто шукає щось новіше та більш мінімалістичне.

На наступній лекції ми детально поговоримо про те, як підключити Swagger (drf-yasg) до вашого Django REST API. Готуйте ваше середовище — на нас чекає багато практики та магії автоматизації!