Зачем
машиночитаемое описание

§1Как README расходится с кодом

Типичный случай при подключении к чужому API. В README написано, что для создания обращения нужно отправить POST /tickets с полем title. Запрос отправлен — в ответ приходит 422: месяц назад в сервис добавили обязательное поле description, а README не поправили.

Причина не в невнимательности автора. README — отдельный текст, который никак не связан с кодом: он не меняется при изменении кода и не проверяется. Пока эта связь держится только на внимательности разработчиков, описание рано или поздно отстаёт.

§2Что такое OpenAPI

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

Ключевые слова здесь — «не зависящее от языка» и «и людям, и программам». Описание учебного сервиса собирается из кода на Python, но читать его будут инструменты, написанные на TypeScript и Go, и разработчик клиента, который Python не знает вовсе.

§3Редакции: 3.1 и 3.2

У спецификации есть собственная версия, и её не нужно путать с версией вашего API. На сентябрь 2026 года последняя опубликованная редакция — 3.2.1 от 10 сентября 2026 года; минорная версия 3.2 вышла 19 сентября 2025 года.

Инструменты догоняют спецификацию не сразу. FastAPI версии 0.115, на которой собран учебный сервис, генерирует описание в редакции 3.1.0:

{
  "openapi": "3.1.0",
  "info": { "title": "Service Desk API", "version": "1.1.0", … },
  "paths": { … }
}

Это не ошибка и не повод менять фреймворк. Редакция 3.1 полностью пригодна для работы, её понимают все инструменты справочника. Важно другое: не путать поле openapi (редакция формата) с полем info.version (версия вашего контракта). Первое здесь 3.1.0, второе — 1.1.0, и меняются они независимо.

§4Кто читает описание

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

Обратите внимание, что все шесть строк — это работа, которую иначе пришлось бы делать руками и заново после каждого изменения. Именно поэтому крупные компании публикуют описание своего API открыто: GitHub держит его в отдельном репозитории и, как сказано в README, использует для проверки запросов к своему API и для контрактных тестов.

§5Описание из кода

Есть два пути получить файл описания. Первый — писать его руками и по нему реализовывать сервис: так делают, когда контракт согласуют раньше, чем начинают разработку. Второй — генерировать описание из кода: так делает FastAPI и так устроен учебный проект.

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

python scripts/export_openapi.py

written openapi/openapi.json
written openapi/openapi.yaml

§6Проверка против расхождения

Файлы в папке openapi/ — это снимок контракта, который лежит в репозитории и виден в истории изменений. Чтобы снимок не отстал от кода, у скрипта есть режим проверки.

python scripts/export_openapi.py --check

Команда собирает описание из кода и сравнивает с файлами в репозитории. Совпало — молчит и завершается успешно. Разошлось — печатает, какой файл устарел, и завершается с ошибкой:

openapi/openapi.json is outdated: run python scripts/export_openapi.py

Эта же команда стоит в CI между тестами и линтером. Изменение, в котором описание не обновлено, не попадёт в основную ветку. За счёт этого описание в репозитории всегда соответствует тому, что сервис отвечает на самом деле.

README расходится с кодом молча. Выгруженное описание расходится громко: сборка падает и называет файл.