Молодцы то что пришли к Swagger и open api схемы это хорошо. Но почему бы не использовать какой нибудь унифицированный протокол с заранее определенной схемой fix/protobuf/sbe? На худой конец делать старые добрые wsdl.
В случае с wsdl было бы, наверное, удобно, если бы мы сами были поставщиками API. Наша задача — предоставить формат, по которому партнерам будет удобно реализовать API, а нам — подключиться. В нашем случае обсуждать и дорабатывать документацию в swagger быстрее.
Как минимизировать ошибки при интеграции с внешними сервисами: опыт онлайн-брокера