Генерация клиента из OpenAPI

Для вызовов API в первую очередь используйте сгенерированный клиент. Он содержит операции и типы из спецификации.

Выбрать источник и генераторВыбрать источник и генератор

1. Если в проекте уже есть сгенерированный клиент для нужного метода и версии, используйте его. При необходимости обновите его штатной командой проекта.
2. Если клиента нет, скачайте openapi.yaml и проверьте нужную операцию в справочнике методов. Этот YAML содержит операции из сценариев для ИИ-агентов. Если метода в нём нет, возьмите спецификацию выбранного стенда со страницы доступа для разработчиков.
3. Используйте генератор, принятый в проекте. Сохраните версию генератора, конфигурацию и исходную спецификацию, чтобы повторить сборку. Поместите сгенерированный код в отдельный пакет или каталог. Настройку транспорта и авторизации добавьте в код проекта рядом с клиентом.

Пример для GoПример для Go

Сохраните скачанный openapi.yaml и файл codegen.yaml из примера в каталоге пакета magistrali внутри Go-модуля. Пример использует oapi-codegen v2.5.1.

Файл codegen.yaml задаёт суффикс HTTPResponse для типов HTTP-ответов клиента, чтобы их имена отличались от имён моделей.

package: magistrali
output: client.gen.go
generate:
  models: true
  client: true
output-options:
  response-type-suffix: HTTPResponse

Сгенерируйте клиент и соберите пакет. Если в модуле ещё нет github.com/oapi-codegen/runtime, добавьте зависимость перед сборкой. Пример проверен с github.com/oapi-codegen/runtime@v1.1.1.

go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.5.1 \
  -config codegen.yaml openapi.yaml
go build .

Подключить и проверитьПодключить и проверить

1. Создайте клиент с базовым URL выбранного стенда. Для защищённых методов подключите заголовок Authorization через настройки транспорта или обработчик запроса клиента. Получайте токен из согласованного источника и ограничьте отправку заголовка доменом выбранного стенда.
2. Соберите проект и проверьте запрос на заглушке или в локальном тесте. Сверьте HTTP-метод, путь, параметры строки запроса и структуру JSON с карточкой метода. Для скачивания файла сохраняйте байты успешного ответа.
3. Если пользователь настроил доступ к тестовому стенду, выполните проверку учётной записи и роли. Для сценариев используйте сгенерированные операции и типы вместе с условиями вызова из карточек.

Если сгенерированный клиент недоступен, для отдельной проверки можно использовать настроенный HTTP-клиент. Соберите запрос по карточке метода и примените те же правила доступа и обработки ответа.