Автоматичне оновлення документації

Уявіть, що ви розробник API, оточений сотнями ендпоінтів.
Якщо кожного разу після зміни API вручну оновлювати документацію,
це може перетворитися на справжній головний біль, гірший, ніж рекурсивний виклик print('Hello, World!').

Автоматизація вирішує цю проблему:

1. Економія часу – автоматичне оновлення документації дозволяє не відволікатися на рутинні задачі.
2. Актуальність – документація завжди відповідає стану вашого API.
3. Зменшення помилок – менше людського фактора → менше невідповідностей і забутих описів.
4. Інтеграція з CI/CD – зручно генерувати документацію під час збірки проєкту та деплою.

Способи автоматичного оновлення документації

Підхід 1: використання drf-yasg і специфікацій OpenAPI

drf-yasg вже робить перший крок до автоматизації. Він генерує документацію на основі опису ваших ендпоінтів у Django Rest Framework: маршрутів, серіалізаторів, описів і навіть коментарів. Проте це лише пів справи — наше завдання йде далі: додати практичні, перевірені механізми оновлення.

Підхід 2: інтеграція в CI/CD пайплайн

Ви можете налаштувати процес генерації документації автоматично при кожному деплої. Наприклад, API змінився, тести пройшли — документація генерується і викладається на сервер. Ми розглянемо, як це зробити на практиці.

Практика: автоматизація за допомогою drf-yasg

Крок 1: підготовка проєкту

Переконайтеся, що drf-yasg встановлений (так, він знову тут!). Додамо потрібні теги та мета-дані до наших ендпоінтів. Ось приклад:

# routes.py
from rest_framework import routers
from myapp.views import MyModelViewSet

router = routers.DefaultRouter()
router.register(r'my-models', MyModelViewSet)

# Припустимо, це підключено до urls.py:
# path('api/', include(router.urls))

Тепер drf-yasg автоматично додасть маршрут у документацію. Якщо ви хочете зробити її красивішою, додайте опис:

# views.py
from rest_framework.viewsets import ModelViewSet
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

class MyModelViewSet(ModelViewSet):
    """
    ViewSet для роботи з MyModel.
    """

    @swagger_auto_schema(
        operation_description="Отримати список об'єктів MyModel",
        responses={200: openapi.Response("Список об'єктів")}
    )
    def list(self, request, *args, **kwargs):
        return super().list(request, *args, **kwargs)

drf-yasg автоматично підхопить цю інформацію.

Крок 2: додаємо автоматичну генерацію OpenAPI-файлу

Згенеруємо статичний файл документації, який можна використовувати для деплою:

python manage.py generateschema > openapi-schema.json

Ось і OpenAPI-специфікації для вашого API! Тепер цей файл можна завантажувати в Swagger UI або Redoc.

Крок 3: Інтеграція в CI/CD

Приклад з GitHub Actions

Налаштуємо процес автоматичного оновлення документації при кожному коміті. Ось приклад конфігурації GitHub Actions:

name: Update OpenAPI Docs

on:
  push:
    branches:
      - main

jobs:
  generate-docs:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: 3.9

    - name: Install dependencies
      run: |
        python -m venv venv
        source venv/bin/activate
        pip install -r requirements.txt

    - name: Generate OpenAPI schema
      run: |
        source venv/bin/activate
        python manage.py generateschema > openapi-schema.json

    - name: Deploy updated schema
      uses: actions/upload-artifact@v3
      with:
        name: openapi-schema
        path: openapi-schema.json

Тепер при кожному оновленні в main документація буде автоматично генеруватися.

Крок 4: деплой документації на сервер

Якщо ви хочете, щоб Redoc або Swagger UI відображали документацію у вебі, додайте маршрут у Django для підключення статичного OpenAPI-файлу:

# urls.py

from django.views.generic import TemplateView

urlpatterns += [
    path('redoc/', TemplateView.as_view(
        template_name='redoc.html',
        extra_context={'schema_url': 'openapi-schema.json'}
    ), name='redoc'),
]

Тепер документація буде доступна за адресою /redoc/.

Перевірка консистентності документації

Навіть автоматизація потребує контролю. Щоб переконатися, що документація та API синхронізовані, скористаємося інструментами для перевірки, наприклад OpenAPI Validator:

1. Встановіть валідатор:

   npm install -g openapi-validator
   

2. Запустіть перевірку:

   openapi-validator validate openapi-schema.json
   

Якщо все ок, отримаємо повідомлення No errors found..

Інтеграція з Redoc CLI

Якщо надаєте перевагу Redoc, можна використовувати Redoc CLI для генерації документації:

1. Встановіть Redoc CLI:

   npm install -g @redocly/cli
   

2. Згенеруйте HTML-документацію:

   redocly build-docs openapi-schema.json -o api-docs.html
   

Тепер можна викласти api-docs.html на сервер.

Поради та найкращі практики

• Слідкуйте за описами: користуйтеся анотаціями в drf-yasg або swagger_auto_schema, щоб документація була інформативною.
• Використовуйте CI/CD: чим більше автоматизації, тим менше ризику забути оновити документацію.
• Тестуйте документацію: переконайтеся, що специфікація OpenAPI валідна і точна.
• Зберігайте документацію окремо: наприклад, вивантажуйте згенеровані файли на S3 або Netlify.

Ось так можна повністю автоматизувати процес документування API і зробити його зручним для команди та користувачів. Висновок? Не забувайте про документацію, вона ваша візитівка у світі API!