Автоматическое обновление документации

Представьте, что вы разработчик 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!

1

Задача

Модуль 3: Django, 23 уровень, 7 лекция

Недоступна

Настройка автоматической генерации документации с помощью команды Django

Настройка автоматической генерации документации с помощью команды Django

Открыть

1

Задача

Модуль 3: Django, 23 уровень, 7 лекция

Недоступна

Интеграция с Git Hooks для автоматизации обновления документации

Интеграция с Git Hooks для автоматизации обновления документации

Открыть