Почему документация API должна жить рядом с контрактом

В больших компаниях API-каталог часто есть.

Но проблема не в том, что его нет.

Проблема в том, что им не всегда удобно пользоваться.

Открываешь ручку — и видишь технические поля. Но не всегда понятно:

- кто владелец; - какое подразделение отвечает; - какая команда поддерживает; - что означает конкретное поле; - какой пример значения ожидается; - можно ли это поле показывать клиенту; - насколько оно критично для сценария.

Поэтому я добавил в контракт механизм annotations — аннотаций.

Идея простая: описание должно жить рядом с операцией.

Например:

- division — подразделение; - team — команда; - project — проект или API; - summary — краткое описание; - description — подробное описание; - exampleVariables — примеры переменных; - field descriptions — описания полей ответа.

В UI, то есть интерфейсе менеджера контрактов, это превращается в понятные вещи:

- фильтры по подразделению, команде и проекту; - portfolio — портфель API-проектов; - карточки операций; - значок `?` рядом с ручкой; - значок `?` рядом с полем; - красивые примеры данных; - описание переменных запроса; - описание response fields — полей ответа.

Это особенно важно в банке.

Потому что API — это не только технический договор.

Это еще и место, где встречаются:

- продукт; - безопасность; - frontend; - backend; - SRE, то есть инженеры надежности; - аналитика; - архитектура; - эксплуатация.

Когда поле непонятно, люди идут в чаты.

Когда owner, то есть владелец, непонятен, люди ищут команду.

Когда пример данных не указан, интеграция идет медленнее.

Когда контракт не связан с проектом, сложно оценить blast radius — радиус влияния изменений.

Поэтому я сделал мультипроектный обзор:

`division -> team -> project -> API -> operation -> field`

Вместо "вот список ручек" появляется карта ответственности.

Для руководителя это тоже полезно.

Он видит не только техническую схему, а портфель API: какие команды публикуют контракты, какие проекты уже подключены, какие ждут публикации, где есть риски.

В какой-то момент прототип перестал быть просто оптимизацией BFF.

Он стал инструментом управления API-ландшафтом.

Но главный вопрос для бизнеса остается прежним:

сколько это может сэкономить?

В следующем посте — про экономику: compute, CDN, OpEx, payback и почему архитектура может возвращать деньги.