OpenAI-совместимый API: как проверять спецификацию клиента

Короткий ответ: спецификация — контракт, а не маркетинговая метка

OpenAPI описывает форму HTTP-контракта: path, метод, заголовки, поля, статусы и иногда примеры. Он не подтверждает качество модели, цену, наличие конкретного model ID, срок хранения или постоянную доступность. Также он не заменяет ручную проверку семантики: поле может быть строкой по схеме, но иметь ограничения tenant, лимит размера или зависимость от версии. Поэтому в репозитории храните проверенную версию схемы рядом с датой получения и источником, а не копируйте фрагмент из чужого SDK или случайной статьи.

Слово «совместимый» разумно трактовать узко: конкретный сценарий проходит на документированном маршруте с конкретной версией adapter. Не отправляйте клиенту обещание «поддерживаем весь OpenAI API». Вместо этого перечисляйте собственные поддерживаемые операции, например создание текстового черновика или получение статуса задачи. Такая граница уменьшает риск, что автогенерация добавит недоступный метод, раскроет ключ в браузере или позволит пользователю выбирать произвольный base URL. Все реальные вызовы остаются server-side и используют ключ, созданный для RussiaAPI.

Снимите минимальный срез спецификации

Для первого клиента достаточно одного operationId, одного request schema, успешного ответа и нескольких ошибок. Уберите из генерации всё, что не нужно продукту: административные маршруты, экспериментальные поля, неизвестные servers и глобальные security schemes. Зафиксируйте версию, checksum и дату проверки. Если API показывает несколько серверов, не принимайте их из ответа пользователя и не пробрасывайте base URL из frontend. Ваш adapter выбирает разрешённый origin из конфигурации сервера после внутренней проверки.

Перед генерацией проверьте обычные ошибки: отсутствующее required поле, лишнее поле, неверный тип, превышение размера, недопустимый enum и неизвестный model ID. Хорошая спецификация делает их различимыми, но код приложения всё равно переводит внешний ответ в собственные стабильные состояния. Например, invalid_input, operation_pending и temporary_unavailable. Пользователю не нужен XML, stack trace или заголовки gateway. Поддержке полезен request_id приложения и версия контракта, но не Authorization и не полный prompt.

Проверяйте изменения как код

Новый файл OpenAPI сначала сравнивают с последним одобренным: исчезновение path, изменение required поля, тип ответа, статус ошибки или security-схема — повод остановить автоматическое обновление. Не допускайте, чтобы генератор молча перезаписал клиент в production. Изменение в схеме проходит pull request, контрактные тесты и небольшой canary. Для каждого поддержанного сценария держите минимальный обезличенный тест: корректный вход, ошибочный вход, проверка timeout и безопасный отказ без ключа.

Особенно осторожно относитесь к nullable, oneOf, свободным object и полям additionalProperties. Они удобны для описания меняющегося ответа, но приложение должно ограничить, что реально принимает. Не передавайте модельный output непосредственно в инструмент, базу, финансовую операцию или роль пользователя. Сначала извлеките только разрешённые поля, проверьте их schema и бизнес-условия. Эта дисциплина актуальна и без опубликованной OpenAPI-схемы: ручной adapter с тестами лучше, чем широкий сгенерированный клиент, основанный на предположениях.

Разделите генерацию клиента и секреты

Сгенерированный клиент не должен жить в браузере, расширении или мобильном приложении, если ему требуется секретный ключ. Frontend вызывает ваш backend с сессией пользователя; backend применяет tenant policy, лимит и allowlist операций. В конфигурации CI используйте переменные окружения и test key только в закрытом серверном окружении. Никогда не добавляйте настоящий ключ, cookie, Authorization header или записанный production-ответ в spec, example, fixture или issue.

Примеры в OpenAPI полезны только если они безопасны и воспроизводимы. Используйте placeholder RUSSIAAPI_API_KEY исключительно в комментарии о среде, а не в коде клиента. Не придумывайте фиксированные model ID: поставьте approved-model-id и потребуйте сверки с актуальным каталогом. При ошибке аутентификации или лимита тест должен удостовериться, что приложение возвращает нейтральный статус, а журнал содержит лишь технические метаданные. Так документация помогает разработке, но не создаёт новый канал утечки.

Сделайте выпуск наблюдаемым и обратимым

После обновления схемы включите новую версию для test tenant или небольшой доли трафика. Смотрите на контрактные ошибки, неизвестные поля, долю timeout, разницу между ожидаемым и фактическим ответом и стоимость по внутренним агрегатам. Не интерпретируйте один успешный запрос как гарантию доступности или совместимости. Если метрики ухудшаются, feature flag возвращает прошлый проверенный adapter, а команда сохраняет request_id и версию контракта для диагностики.

RussiaAPI не обещает полный набор функций другого поставщика только потому, что интеграция использует знакомую форму. Перед расширением использования подтвердите конкретный маршрут, модель, параметры и условия в текущем каталоге и документации. Проверьте права доступа и обработку данных внутри своей организации. Этот процесс занимает больше времени, чем копирование SDK, но делает изменение API контролируемым: команда знает, что именно тестировала, какие допущения применяла и как безопасно откатиться.

Server-side пример

Пример показывает локальную проверку или контроллер на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

import { createHash } from 'node:crypto';

export function validateMinimalSpec(spec) {
  const path = spec?.paths?.['/v1/chat/completions']?.post;
  if (spec?.openapi?.startsWith('3.') !== true) throw new Error('openapi_3_required');
  if (!path?.operationId || !path?.responses?.['200']) throw new Error('minimal_contract_missing');
  return { operationId: path.operationId, sha256: createHash('sha256').update(JSON.stringify(spec)).digest('hex') };
}

// Run with a reviewed local JSON file; do not embed credentials in the spec or fixtures.
// Confirm the actual route and fields in the current RussiaAPI documentation before use.

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