Код як схема: проєктування суворих API для автономних ШІ-агентів та клієнтських SDK
Фінтех-компанія Increase детально описала внутрішній фреймворк, що генерує специфікації OpenAPI 3.1 безпосередньо з типізованого коду. Перенесення валідації на етап збірки дозволило одному інженеру підтримувати сотні ендпоінтів для ШІ-агентів.
Чому це важливо
Впроваджуйте генерацію схем на основі типізованого коду, щоб уникнути розсинхронізації документації та надати ШІ-агентам детерміновані інтерфейси.
TL;DR
- 01Описуйте інтерфейси ендпоінтів у типізованому бекенд-коді замість ручної підтримки окремих файлів YAML.
- 02Виявляйте відсутність описів полів та помилки типів на етапі збірки в CI за допомогою статичних аналізаторів.
- 03Експортуйте специфікації OpenAPI 3.1 із дискримінаторами та описами enum для точної роботи агентів під час виклику інструментів.
Ключові факти
- Цільова специфікація
- OpenAPI 3.1
- Мова та типізація
- Ruby зі статичною перевіркою типів Sorbet
- Розмір команди DX
- 1 інженер на сотні публічних ендпоінтів
Ліквідація розсинхронізації схем у джерелі
Підтримка сотень ендпоінтів API вручну створює проблеми як для інженерів, так і для автономних агентів. Замість ручного написання OpenAPI чи окремої підтримки документації, Increase використовує виконуваний код як єдине джерело правди. Кожен метод наслідує абстрактний клас, що фіксує HTTP-метод, шлях, форму параметрів і структуру відповіді.
class AccountCreate < APISchema::AbstractAPIMethod
string :name, documentation: AccountResource.attributes.name.documentation
enum :funding,
documentation: AccountResource.attributes.funding.documentation,
cases: AccountResource.attributes.funding.cases
def operate
account = Model::Account.create!(name: params.name, funding: params.funding)
AccountResource.from_model(account)
end
endПеревірки на етапі збірки та гідратація моделей
Фреймворк вимагає суворого дотримання конвенцій до виконання коду в продакшені. Пропуск опису атрибутів або параметрів блокує проходження типізації Sorbet під час збірки. Абстракції на кшталт resource_id безпечно завантажують сутності з бази даних (Model::Account) і передають готовий об'єкт у метод. Перевірка помилок у назвах параметрів, відповідності середовища та прав доступу виконується фреймворком до бізнес-логіки з агрегацією всіх помилок в один об'єкт.
Експорт багатого OpenAPI 3.1 для агентів та SDK
Механізм рефлексії транслює визначення класів у схему OpenAPI 3.1. Ресурси конвертуються у повторно використовувані $ref, що захищає клієнтські генератори коду від дублювання класів. Додатково експортуються складні структури з discriminator та описи окремих значень enum. Ця схема стає фундаментом для виклику інструментів ШІ-агентами, типізованих SDK та документації без ризику розбіжностей.
Спробуй за 2 хвилини
class AccountResource < APISchema::AbstractResource
string :id, documentation: "The Account identifier"
string :name, documentation: "The name of the Account"
enum :funding, documentation: "The type of the Account", cases: {
deposits: "A depository account such as checking or savings"
}
timestamp :created_at, documentation: "When the Account was created"
endruby
✓ Коли використовувати
- Створення публічних платформ для розробників, де потрібна синхронізація SDK, документації та інструментів ШІ.
- Проєкти, де виникає регулярна розсинхронізація між реальною логікою бекенду та застарілими специфікаціями.
✕ Коли НЕ варто
- Швидке прототипування мікросервісів, коли контракти змінюються щогодини в нестабільному коді.
- Прості внутрішні скрипти, де не потрібні зовнішні SDK або інтеграція з автономними ШІ-агентами.
Що зробити сьогодні
- Проведіть аудит наявних схем API на предмет відсутності описів параметрів та значень enum.
- Налаштуйте статичну перевірку типів у CI для обов'язкової наявності документації біля кожного поля ендпоінта.
- Експортуйте специфікації OpenAPI 3.1 для генерації маніфестів Model Context Protocol (MCP) та інструментів ШІ-агентів.
Що каже спільнота
“I wrote some thoughts on the workflow we use to publish our API documentation and related artifacts. I'm curious if others are doing similar or if there are other ways to do this.”