Как документировать API с помощью OpenAPI и Swagger

Короткий ответ

OpenAPI — это стандартный формат описания HTTP API: какие есть эндпоинты, какие параметры они принимают, что возвращают и как защищены. Swagger — набор инструментов вокруг этого формата: Swagger UI показывает интерактивную документацию, Swagger Editor помогает писать спецификацию. Исторически формат тоже назывался Swagger, поэтому слова часто путают.

Рабочая схема простая: одна спецификация — один источник правды. Из неё строится документация, генерируются клиенты и проверяются запросы.

Как выглядит спецификация

Минимальный пример на YAML:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      summary: Получить заказ
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Заказ найден
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Заказ не найден
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: integer
        status:
          type: string
          enum: [new, paid, shipped]

Главные разделы:

• info — название и версия API.
• paths — эндпоинты и HTTP-методы.
• components/schemas — переиспользуемые модели данных, на которые ссылаются через $ref.
• securitySchemes — как работает авторизация (Bearer-токен, API-ключ, OAuth2).

Что получается из одной спецификации

• Документация. Swagger UI или Redoc рендерят файл в удобную страницу, где можно отправить тестовый запрос прямо из браузера.
• Типизированные клиенты. Генераторы (например, OpenAPI Generator или openapi-typescript) создают типы и SDK для TypeScript, Kotlin, Swift, Python и других языков. Фронтенд и мобильная команда перестают вручную описывать модели.
• Моки. По спецификации можно поднять фейковый сервер и начать фронтенд до готовности бэкенда.
• Валидация. Middleware проверяет входящие запросы и ответы на соответствие схеме.

Code-first или spec-first

Во многих фреймворках code-first работает из коробки: FastAPI строит спецификацию из типов Python, NestJS — из декораторов, для Express и Fastify есть плагины на основе схем валидации.

Spec-first полезен, когда контракт важнее реализации: фронтенд, мобильное приложение и партнёры договариваются об API заранее и работают параллельно.

Как не дать документации устареть

1. Один источник правды. Либо спецификация генерируется из кода, либо код проверяется по спецификации. Не держите два независимых описания.
2. Проверка в CI. Линтер (например, Spectral или Redocly CLI) ловит ошибки в спецификации. Отдельный шаг сравнивает сгенерированную спецификацию с закоммиченной.
3. Контрактные тесты. Тесты отправляют запросы и сверяют ответы со схемой.
4. Детектор breaking changes. Инструменты сравнения спецификаций показывают, что удалено поле или изменился тип, ещё до релиза.
5. Версионирование. Ломающие изменения — только с новой версией API или с периодом поддержки старого поведения.

Частые ошибки

• Нет примеров. Добавляйте example к схемам — документация становится понятнее в разы.
• Описаны только успешные ответы. Ошибки 400, 401, 404, 422 тоже часть контракта.
• Дублирование схем. Выносите модели в components и ссылайтесь через $ref.
• Пустые описания. Поле description должно объяснять смысл, а не повторять название.
• Документация вручную в Notion или Word. Она устаревает после первого же релиза.

Официальная спецификация формата: spec.openapis.org.