📑 Что должно быть в документации по интеграциям?

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

Что такое интеграция между системами? Это "диалог" между системами. И работа аналитика сводится к созданию сценария взаимодействия для такого "диалога".
Сам сценарий мы рассмотрим внимательно в следующий раз. Но чтобы документация была полноценной, нужно указать дополнительные атрибуты.

🎾 Протоколы обмена информацией
В моей практике в одной интеграции встретились сразу 3 протокола обмена. И не стоит забывать указывать это в документации.

🎾 Sequence diagrams
Бывает, что потребители документации не хотят знать подробностей о работе систем. Для верхнеуровневого обзора последовательности шагов взаимодействия подойдет sequence диаграмма.

🎾 Входящие и исходящие параметры запросов
У входящих указываем тип и обязательность полей. Если лень описывать, то можно приложить ссылку на свагер. Если у вас еще остались силы, то было бы идеально приложить примеры запроса и ответа. Не забывайте, что ответы могут быть успешными и неуспешными, поэтому примеры стоит приводить на оба кейса.

🎾 Детальные описания всех используемых процедур
Основная работа происходит в сторонних системах, поэтому всегда важно указать, либо описание, либо ссылки на используемые процедуры и параметры запросов к ним.

🎾 Модель физических данных, если она предусмотрена проектом.
или ERD. Редкая интеграция обходится без участия базы, поэтому не забывайте прописывать ее.

Именно такую схему я использую при создании документации для интеграций.