Когда команда разрабатывает API без документации, это рано или поздно заканчивается одинаково: фронтендеры пишут в чат «а что возвращает этот эндпоинт?», бэкендеры тратят час на объяснения, и цикл повторяется. Хорошая документация — это не формальность и не «сделаем потом». Это часть продукта.

Swagger и OpenAPI — в чём разница

Многие используют эти слова как синонимы, но это не так.

Swagger — набор инструментов, который придумала компания SmartBear. Изначально они создали формат для описания API, потом выпустили инструменты поверх него: Swagger UI, Swagger Editor, Swagger Codegen.

В 2015 году SmartBear передала сам формат в OpenAPI Initiative — консорциум, куда вошли Google, Microsoft, IBM и другие. С тех пор формат называется OpenAPI Specification (OAS). Swagger — это инструменты, OpenAPI — это стандарт.

Сейчас актуальная версия — OpenAPI 3.1, вышедшая в 2021 году и полностью совместимая с JSON Schema. До этого многие использовали 3.0 или даже Swagger 2.0 (он же OpenAPI 2.0). Если коллеги говорят «у нас есть свагер» — скорее всего, они имеют в виду файл в формате OpenAPI плюс Swagger UI поверх него.

Как выглядит OpenAPI-файл

OpenAPI-документ — это YAML или JSON файл, который описывает всё, что есть в вашем API: эндпоинты, параметры, схемы данных, методы аутентификации, возможные ответы.

Вот минимальный пример:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Пользователь найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Структура файла делится на несколько ключевых блоков:

  • info — метаданные: название, версия, описание, контакты
  • paths — все эндпоинты с описанием параметров и ответов
  • components — переиспользуемые схемы, параметры, ответы
  • servers — базовые URL для разных окружений
  • security — схемы аутентификации

Блок components особенно важен: вместо того чтобы описывать схему User в каждом эндпоинте, вы описываете её один раз и ссылаетесь через $ref. Это сильно упрощает поддержку.

Два подхода: code-first и design-first

Code-first — вы пишете код, а документация генерируется из аннотаций. В Spring Boot это делается через springdoc, в FastAPI документация генерируется автоматически из type hints, в NestJS — через декораторы @ApiOperation и @ApiResponse.

Плюсы: документация всегда синхронизирована с кодом, не нужно тратить отдельное время на написание. Минусы: качество страдает. Автогенерированные описания часто выглядят как «Returns 200» и пустые description — всё равно нужно дополнять вручную.

Design-first — вы начинаете с написания OpenAPI-спецификации, договариваетесь о контракте между командами, и только потом пишете код. Это API-first подход.

Плюсы: фронтенд и бэкенд могут работать параллельно — фронт мокает ответы по спецификации, пока бэкенд пишет реальную логику. Меньше переделок, лучше архитектура. Минусы: нужна дисциплина поддерживать спецификацию актуальной.

На практике многие команды делают гибрид: автогенерируют базовую структуру из кода, потом дополняют вручную.

Инструменты для работы с документацией

Swagger UI — самый распространённый способ отобразить OpenAPI-документ. Интерактивная HTML-страница, где можно видеть все эндпоинты и сразу отправлять запросы прямо из браузера. Легко встраивается в любой проект.

Redoc — альтернатива с более чистым дизайном. Трёхколоночный layout, примеры кода на разных языках, хорошо выглядит как публичная документация. Не поддерживает отправку запросов из браузера, зато читается лучше.

Stoplight Studio — визуальный редактор для OpenAPI. Удобно, если не хочется писать YAML вручную. Есть проверка на ошибки, мокинг, публикация.

Scalar — относительно новый инструмент, набирает популярность. Современный дизайн, поддерживает OpenAPI 3.x, интерактивный клиент запросов. Некоторые команды переходят на него с Swagger UI.

Postman — умеет импортировать OpenAPI-файлы и превращать их в коллекции запросов, удобно для тестирования.

Для внутренних API чаще используют Swagger UI — он просто работает. Для публичных API, где важен внешний вид, лучше смотреть на Redoc или Scalar.

Что делает документацию действительно полезной

Технически правильный OpenAPI-файл — это ещё не хорошая документация. Вот что реально помогает:

Примеры данных. Каждая схема должна иметь example или examples. Абстрактные типы string и integer мало что говорят. Реальный пример говорит всё:

User:
  type: object
  properties:
    id:
      type: integer
      example: 42
    name:
      type: string
      example: "Иван Петров"
    email:
      type: string
      format: email
      example: "ivan@example.com"

Описание ошибок. Не ограничивайтесь 200 OK. Опишите все коды: 400 (что именно невалидно?), 401 (не авторизован), 403 (нет прав), 404, 409 (конфликт), 422 (ошибка валидации с деталями), 500. И для каждого — схема тела ответа с понятными полями error и message.

Описание аутентификации. Если API требует токен, опишите это в блоке securitySchemes и укажите, какие эндпоинты его требуют. Казалось бы, очевидно — но половина API-документаций этого не делает.

Группировка через tags. Добавьте теги к эндпоинтам — users, orders, payments. Swagger UI и Redoc автоматически сгруппируют их, и в документации будет навигация.

Описание параметров запросов. Для query-параметров укажите не только тип, но и допустимые значения, дефолт, формат. Если есть sort с вариантами asc/desc — укажите это через enum.

Версионирование API и документации

Версий может быть несколько: /api/v1/users и /api/v2/users. OpenAPI позволяет описать разные версии в разных файлах или в одном через блок servers:

servers:
  - url: https://api.example.com/v1
    description: Stable
  - url: https://api.example.com/v2
    description: Beta

Практически удобнее держать отдельный файл на каждую версию. Старую версию помечают как deprecated и убирают через 6–12 месяцев. В описаниях эндпоинтов и полей есть флаг deprecated: true — используйте его, когда что-то устаревает. Это лучше, чем молча убирать.

Автогенерация SDK и mock-серверы

Хороший OpenAPI-файл — это не только документация. Из него можно автоматически генерировать:

Клиентские SDK. Инструменты вроде openapi-generator умеют генерировать клиентский код на десятках языков: TypeScript, Python, Java, Go, Swift. Качество зависит от качества спецификации — чем детальнее описаны схемы, тем лучше результат.

Mock-серверы. Prism от Stoplight или Microcks поднимают сервер, который отвечает на запросы по спецификации с примерами данных. Это позволяет фронтенду работать до того, как бэкенд готов.

Валидация на сервере. Библиотеки вроде express-openapi-validator автоматически валидируют входящие запросы и исходящие ответы по спецификации — это ловит расхождения ещё до деплоя.

Тесты. Dredd и другие инструменты прогоняют тесты против живого API, проверяя соответствие реальных ответов спецификации.

Главная проблема: документация устаревает

Документация, которая врёт, хуже отсутствия документации. Разработчик доверяет спецификации, пишет код — и обнаруживает, что реальный API ведёт себя иначе.

Несколько способов держать её актуальной:

Contract testing. Pact и аналоги проверяют, что producer (бэкенд) выполняет контракт, на который рассчитывает consumer (фронтенд или другой сервис). Запускается в CI/CD.

Response validation. Некоторые команды добавляют мидлвар, который логирует расхождения между реальными ответами и спецификацией. Не блокирует запросы, но сигнализирует.

Правило одного PR. Изменение API = изменение OpenAPI-файла в том же пул-реквесте. Дисциплинарный вопрос, но принципиальный.

Идеальный вариант — пишете минимальное в аннотациях, а дополнительные описания и примеры добавляете в отдельном файле, который мержится с автогенерацией через скрипт. Сложнее, зато сочетает оба подхода.

Когда обращаться к специалистам

Если вы запускаете продукт с нуля или переходите на микросервисную архитектуру, архитектура API и её документация — это то, что стоит сделать правильно с первого раза. Переделывать контракты между сервисами дорого.

В REEXY интеграция сервисов и разработка API стартует от 1 500 ₽ — это актуально для малого бизнеса, который хочет автоматизировать процессы без переплат.

Чек-лист перед публикацией API

Перед тем как отдать документацию команде или внешним разработчикам:

  • Все эндпоинты описаны, включая методы, параметры и тела запросов
  • Для каждого поля есть тип и пример
  • Описаны все возможные коды ответов, не только 200
  • Схема аутентификации указана явно
  • Эндпоинты сгруппированы по тегам
  • Есть информация о версии и контакт для вопросов
  • Документация проверена на валидность через Swagger Editor или аналог
  • Mock-сервер или Swagger UI доступен команде

Это минимум. Хорошая документация — ещё и руководство по началу работы, примеры сценариев использования, FAQ по частым ошибкам. Но начните с этого списка, и уже будет в разы лучше среднего.