Документация API: OpenAPI, примеры и как держать её актуальной

Документация API нужна всем, кто с ним работает: фронтенду, мобильному приложению, партнёрам и новым разработчикам. Стандарт де-факто — спецификация OpenAPI, из которой автоматически строятся интерактивная документация, клиенты и тесты. Чтобы документация не устаревала, её генерируют из кода или проверяют на соответствие коду в CI при каждом изменении.

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

Что такое OpenAPI?

OpenAPI — это формат описания HTTP API в YAML или JSON: какие есть эндпоинты, какие параметры они принимают, что возвращают, какие бывают ошибки и как проходить авторизацию. Это машиночитаемый контракт, из которого инструменты строят документацию, клиентские библиотеки, моки и проверки.

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: Заказ не найден

Что даёт спецификация:

• интерактивная документация — можно отправить запрос прямо со страницы;
• генерация клиентов — типизированный код для фронтенда и мобильных приложений;
• моки — фронтенд работает с фиктивным API, пока бэкенд в разработке;
• проверки — тесты сверяют реальные ответы со спецификацией.

Сначала контракт или сначала код?

Есть два подхода: сначала написать спецификацию, обсудить и утвердить её, а потом реализовать (contract-first), или писать код и генерировать спецификацию из него (code-first). Первый лучше для публичных API и параллельной работы нескольких команд, второй — для внутренних API небольших команд.

Критерий	Contract-first	Code-first
С чего начинают	С файла спецификации	С кода эндпоинтов
Параллельная работа	Фронтенд стартует сразу на моках	Ждёт реализации
Риск расхождения	Нужна проверка кода на соответствие	Низкий, спецификация из кода
Подходит для	Публичных и партнёрских API	Внутренних API, быстрых изменений

Про проектирование эндпоинтов — статьи как спроектировать REST API и REST, GraphQL или gRPC.

Фото: Unsplash

Что должно быть в хорошей документации?

Хорошая документация отвечает на вопросы разработчика без переписки с автором: как получить доступ, как сделать первый запрос, что значит каждая ошибка и что изменилось в последней версии. Одной автоматической спецификации для этого мало — нужны пояснения и примеры.

1. Быстрый старт. Как получить ключ и сделать первый успешный запрос за пять минут.
2. Авторизация. Способ, срок жизни токенов, обновление — подробнее в статье сессии, JWT и OAuth.
3. Примеры. Реальные запросы и ответы для каждого эндпоинта, а не только схемы.
4. Ошибки. Единый формат ошибок, список кодов и что с ними делать.
5. Лимиты. Ограничения частоты запросов и размера данных — подробнее в статье rate limiting.
6. Вебхуки. Какие события приходят, как проверять подпись и что делать при повторах.
7. Журнал изменений. Что изменилось, когда, и есть ли несовместимые изменения.

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

Документация устаревает, когда её обновляют вручную отдельно от кода. Решение — сделать её частью процесса разработки: спецификация лежит в репозитории, меняется в том же пулл-реквесте, что и код, а CI проверяет, что они совпадают.

• спецификация хранится в репозитории рядом с кодом;
• изменения API без изменения спецификации не проходят ревью — см. статью код-ревью: как устроить;
• контрактные тесты проверяют, что ответы соответствуют схеме;
• линтер спецификации ловит несовместимые изменения;
• документация публикуется автоматически при каждом релизе.

Как документация помогает бизнесу?

Документация экономит время команды и партнёров: быстрее подключаются интеграции, меньше вопросов в поддержку, проще передать проект другой команде. Для продуктов, где API — часть предложения клиентам, качество документации напрямую влияет на продажи.

• новые разработчики начинают работать за дни, а не недели — подробнее в статье онбординг разработчика;
• партнёры подключаются без созвонов с вашими программистами;
• при смене подрядчика знания об API не теряются;
• технический аудит проходит быстрее и дешевле.

Коротко

• OpenAPI — стандартный машиночитаемый контракт API.
• Из спецификации строятся документация, клиенты, моки и проверки.
• Contract-first — для публичных API и параллельной работы, code-first — для внутренних.
• Хорошая документация включает быстрый старт, примеры, ошибки, лимиты и журнал изменений.
• Спецификация живёт в репозитории и проверяется в CI, иначе она устареет.