Как обновлять OpenAPI вместе с кодом с помощью ИИ
Сопоставление контракта вместо правдоподобной документации

В API поле количества уже ограничено сотней единиц, а документация по-прежнему обещает тысячу. Агент может быстро заменить число в схеме. Но сначала нужен ответ: устарела документация или код нарушил согласованный контракт?

Возьмём учебную операцию создания заказа. В приложении есть маршрут, проверка доступа, входные данные, обработчик и сериализация ответа. Ниже нет отчёта об аудите конкретного проекта: это порядок работы, который можно применить к своей операции, проверяя каждый вывод по исходникам и согласованной спецификации.

Выберите версию и источник описания

Пример использует OpenAPI 3.1.1. В OpenAPI описание операции включает входные данные и ответы; схемы можно переиспользовать через components и ссылки. Обязательность тела запроса и обязательность его отдельных полей задаются в разных местах. Эти правила описаны в Request Body Object и Schema Object.

В рабочем проекте сначала найдите его версию OpenAPI и генератор. Не переводите документ на новую версию только ради примера из статьи. Также выясните, какой файл редактируется: исходные аннотации, атрибуты, YAML или результат генерации. Правка сгенерированного JSON может исчезнуть при следующем запуске.

Соберите доказательства по одной операции

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

Исследуй POST /api/orders и его существующее OpenAPI-описание.
До правок сопоставь:
— маршрут и условия доступа;
— обязательные входные поля и ограничения значений;
— успешный ответ, статус и сериализацию;
— подтверждённые ветки ошибок и их преобразование в HTTP;
— существующие общие схемы.

Каждое расхождение снабди источником в коде и указателем в спецификации.
Если контракт неоднозначен, сформулируй вопрос. Не выбирай сторону молча.

Для упражнения договоримся о результате исследования: тело обязательно; quantity — обязательное целое от 1 до 100; успешный ответ использует 201. Эти условия заданы здесь как учебный контракт. В реальном API их надо подтвердить, а не скопировать из типичного примера создания заказа.

Измените только подтверждённый фрагмент

В уже существующей операции фрагмент тела может выглядеть так. Это часть документа, а не самостоятельная спецификация и не полный контракт заказа.

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - quantity
        properties:
          quantity:
            type: integer
            minimum: 1
            maximum: 100

Не добавляйте туда адрес доставки, валюту или поле скидки только потому, что они обычно встречаются у заказов. Если существует общая схема запроса, проверьте её других потребителей перед изменением. Исправление общей maximum может затронуть операцию, которая действительно допускает другое количество.

Пример запроса тоже должен соответствовать подтверждённой форме. Вымышленное поле выглядит особенно убедительно в красивом интерфейсе документации, но оформление не превращает его в обещание сервера.

Не восстанавливайте ошибки по привычке

Наличие авторизации не позволяет автоматически вписать привычный набор кодов ошибок. Найдите, как приложение отвечает на отсутствие доступа, неверные данные и бизнес-конфликт именно для этой операции. Возможны общая оболочка ошибки, дополнительные заголовки и различия между окружениями.

Если код, тест и действующая схема расходятся, зафиксируйте три версии. Например, обработчик возвращает 201, тест ожидает 200, схема содержит оба без объяснения. Агент может показать противоречие и затронутых клиентов; решение о публичном поведении принимает разработчик.

Условия доступа тоже нельзя выводить только из имени middleware. Описание механизма аутентификации и фактическое разрешение создавать заказ в конкретной организации — разные вопросы. Не обещайте в документации правила, которые никто не проверял.

Проверьте документ и соответствие реализации отдельно

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

Для quantity полезны границы: отсутствие поля, ноль, один, сто и сто один. При согласованном целочисленном контракте отдельно проверьте дробное значение. Правила приведения строк к числам могут различаться; если сервер принимает строку, а схема обещает только число, это повод обсудить контракт, а не механически переносить имя правила валидатора.

Сравните успешный ответ с его схемой: обязательные поля, вложенность, возможное отсутствие значения. Затем проверьте выбранную ошибку. Если тесты используют заглушку внешнего сервиса, в отчёте укажите, какую часть они подтверждают, а какую не проверяют.

Включите обновление схемы в обычную задачу

При изменении входных полей, ответа или публичной ошибки просите агента найти затронутую операцию и её потребителей. В итоговом diff должны быть согласованы реализация, описание и проверки. Если API не менялся, не нужно переписывать документацию ради формального пункта.

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

Для контекста о самой документации API есть архивная статья о Swagger и OpenAPI. Здесь следующий шаг — сделать рассинхронизацию видимой до выпуска. Агент сокращает механическую работу сопоставления, но ответственность за обещанный клиентам контракт остаётся у человека.