Добрый день!

Сегодня пост немного не по теме DevOps. Пост про интеграции.

Каждый в своей работе сталкивался с описанием интеграции с другими системами и наверняка видел прекрасные эксель-таблички для описания передаваемой в пакетах информации.
Я почти уверен, что вы знакомы с ситуацией, когда от вас ждут "тестовый JSON" для того чтобы начать тестировать интеграцию с другой системой. И тут вам приходится или рисовать его из головы, или в авральном темпе писать какие-то костыли для его генерации.
Ну а поддержание документации в актуальном виде после релиза... это для многих за гранью фантастики.

На самом деле, все можно поменять если перейти на описание спецификаций к вашим api по международному стандарту OpenApi. Отдавая информацию о вашем программном интерфейсе в таком виде, вы снимите большинство вопросов о том, как интегрироваться с вашей системой. А в процессе описания, с большой долей вероятности, наткнетесь на ошибки проектирования собственной системы.
Даже если вы интегрируетесь только в рамках своего предприятия и вам кажется что описание спецификации вашего апи это лишние трудозатраты, подумайте какие возможности дает такое описание для реализации авто-тестирования Апи или для его разработки.

Пишите в комментариях как вы сейчас описываете интеграции на текущем месте работы.