OpenAPI diff для OpenAI-совместимого API

Сохраните проверяемый снимок контракта

Начните с исходной спецификации, которую ваш адаптер действительно использовал в последнем успешном выпуске. Сохраните её в репозитории или доверенном артефактном хранилище с датой, источником, хешем и владельцем. Не подменяйте снимок HTML-страницей, случайной коллекцией Postman или ответом модели: diff должен сравнивать одинаковый тип документа. Если живой контракт выдаётся динамически, зафиксируйте момент получения и отдельно отметьте, что модельный каталог, цены и права могут изменяться вне этой спецификации. Такой снимок не замораживает внешнюю среду, но делает обсуждение изменения конкретным и воспроизводимым.

Разделите совместимые и опасные изменения

Добавление необязательного поля часто менее рискованно, чем удаление endpoint или изменение типа обязательного параметра, но окончательное значение зависит от вашего клиента. В правилах diff помечайте как требующие review удаление пути, смену HTTP-метода, изменение required, сужение enum, изменение формата ответа и появление нового требования аутентификации. Новая необязательная возможность тоже может быть опасна, если клиент передаёт объект без allowlist. Не делайте вывод о безопасности только по слову compatible: сравните влияние на конкретные вызовы, сериализацию, обработку ошибок и retry. Неизвестное изменение должно останавливать автоматический rollout, а не тихо уходить в production.

Запускайте diff в CI без секретов

CI получает две спецификации и выводит нормализованный отчёт, но не нуждается в реальном API-ключе, пользовательских payload или заголовке Authorization. Ограничьте входные URL и размер файла, проверьте подпись либо доверенный источник артефакта и запускайте анализ в отдельной задаче. В отчёте храните идентификаторы версий, хеши, найденные классы изменений и ссылку на review. Если для smoke test нужен живой gateway, используйте отдельный сервисный контекст и обезличенный fixture на сервере; не вкладывайте секрет в лог CI. Разделение статического diff и сетевого теста позволяет расследовать изменение без расширения доступа.

Свяжите спецификацию с адаптером

Одна и та же OpenAPI-версия полезна только вместе с кодом, который её интерпретирует. В manifest выпуска укажите версию адаптера, хеш базовой и новой спецификации, набор затронутых сценариев и решение review. Когда клиент строит URL, сериализует tools или читает streaming-ответ, добавьте контрактные тесты на минимальный поддерживаемый маршрут и ожидаемую локальную ошибку. Не тестируйте скрытые рассуждения модели и недокументированные поля. Если diff показывает новый enum или response shape, сначала обновите парсер в feature branch, затем прогоните отрицательные fixtures и только после этого разрешайте флаг нового пути.

Подтвердите наблюдаемое поведение маленьким тестом

Спецификация говорит о намерении контракта, но не гарантирует фактические права, доступность модели или лимиты. После review запустите маленький server-side smoke test с синтетическим текстом, жёстким дедлайном и локальным operation ID. Проверьте статус, форму ожидаемых полей и безопасную обработку негативного сценария, например неизвестной модели или неверного параметра. Не отправляйте данные клиентов и не превращайте один HTTP 200 в доказательство полной совместимости. При несовпадении сохраните нормализованную сводку, остановите rollout и вернитесь к старому адаптеру, если это допускает ваша локальная policy.

Сделайте rollback частью решения

До включения новой версии подготовьте предыдущий manifest и понятное условие отката: критичное расхождение схемы, рост validation_error, повторяемая ошибка адаптера или недоступный обязательный маршрут. Rollback меняет только ваш выбор версии и журналирует решение; он не должен повторно запускать неизвестную операцию пользователя на другом маршруте. После инцидента сравните исходную спецификацию, отчёт diff, версию SDK и обезличенный тестовый набор. Обновляйте правила классификации только после review. Актуальные endpoint, ограничения и коммерческие условия всё равно подтверждаются в текущих документах и договоре, а не в старом файле OpenAPI.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. Он не содержит реального ключа и показывает логику приложения; перед интеграцией подтвердите текущую схему, маршрут и ограничения в документации.

export function classifyChange(before, after) {
  const changes = [];
  for (const path of Object.keys(before.paths ?? {})) {
    if (!after.paths?.[path]) changes.push({ severity: 'block', path, reason: 'path_removed' });
  }
  for (const [path, item] of Object.entries(after.paths ?? {})) {
    for (const method of Object.keys(item)) {
      if (!before.paths?.[path]?.[method]) changes.push({ severity: 'review', path, reason: 'operation_added' });
    }
  }
  return changes;
}
// Compare trusted static specification snapshots in CI; validate live behavior separately.

Проверьте синтаксис через node --check, добавьте аутентификацию, лимиты и отрицательные тесты. Не записывайте в журнал тело запроса целиком или заголовки авторизации.

Перед production выполните тест в отдельном environment, назначьте владельца проверки и зафиксируйте результат без чувствительных данных. Повторяйте проверку при смене версии клиента, модели или серверной policy.

Граница ответственности

Это руководство описывает защитные механизмы вашего приложения, а не гарантии конкретного провайдера или модели. Не передавайте в браузер, статьи, тикеты или логи API-ключи, заголовки Authorization, cookie, исходные ключи поставщиков либо полные пользовательские данные.

Материалы для сверки

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

• OpenAPI Specification
• OWASP Top 10: контроль изменений и безопасная интеграция