Документирование сообщений AMQP

Какова была бы лучшая практика для документирования сообщений AMQP? Моя компания разрабатывает несколько отдельных внутренних приложений (отдельными командами), которые общаются друг с другом с помощью асинхронного обмена сообщениями RabbitMQ. В каждом типе связи используется формат пользовательских сообщений, например, событие, опубликованное «документ»:

$documentPublishedEvent = array( 'document_type' => 'invoice', 'published_on' => '2012-02-15', 'published_by' => 'jim', ); 

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

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

  • хорошая старая вики (разделяемая между командами) – у каждого сообщения может быть подробное объяснение здесь – проблема в том, что мы не будем знать, если вики-обновления или некоторые детали отсутствуют
  • общий компонент Composer со специальным классом для каждого типа сообщений (например, класс DocumentPublishedEvent) – каждое приложение может включать этот компонент, но проблемы сложны, поскольку каждое приложение может «видеть» все возможные сообщения (даже если они не используют их) , и необходимость обновить зависимость композитора сразу сразу после выхода новой версии

Есть ли лучший вариант?

Solutions Collecting From Web of "Документирование сообщений AMQP"

Вы можете использовать специальную концепцию класса в каждом приложении без поддержки композитора и генерировать документацию из этих специальных классов. Напишите сценарий, который после пакета / развертывания кода выведет любой формат документации, который вы предлагаете. Еще проще, если вы используете пакет Composer, который обрабатывает публикацию / документацию этих классов, так что каждое приложение имеет один и тот же API для RabbitMQ и включает в себя создание документации.

Каждому приложению нужны только классы, которые он использует для публикации. Результатом процесса является документация, которая обновляется каждый раз при развертывании.