Документирование API шины сообщений?

Question

Я искал последние пару дней, чтобы каким-то образом документировать API для архитектуры микросервисов, над которой я работаю. Во-первых, я дам очень быстрое описание проекта:

• Написано в C#, .NET 4.6.1
• Использование NetMQ с х-паб/х-суб-прокси как «сообщение брокера»
• Все коммуникации объекты равнину C# сериализовать в формате JSON
• Некоторые клиенты JavaScript в браузере, другие приложения .NET

короткий этого является то, что я хотел бы знать, как другие люди, документировать модели, опубликованные в их сообщении bu s. Я видел немало проектов (например, Swagger), которые помогают документировать вызовы REST, но мы не используем REST. Наше приложение практически полностью основано на событиях с обменом сообщения pub-sub с использованием JSON.

Моя первая мысль заключалась в том, чтобы задокументировать JSON с помощью JSON-Schema и использовать инструмент для преобразования этого файла в хорошо отформатированные документы API. Это, вероятно, будет работать нормально, но меня беспокоит то, что, похоже, нет никаких инструментов для автоматизации генерации схемы как части процесса сборки. Если наши модели отклоняются от документации API, я хочу, чтобы это была ошибка сборки. Еще лучше, если бы какой-то способ автоматически генерировать базовую документацию как часть процесса сборки, документы могли быть синхронизированы.

Как вы, ребята, это делаете? Отсутствие инструментов документации, характерных для архитектуры шины сообщений в пользу REST, заставляет меня подвергнуть сомнению наше решение использовать архитектуру обмена сообщениями на основе очередей сообщений. :)

Answer 1

... кажется, не существует какие-либо инструменты, чтобы автоматизировать схемы поколения ...

Согласован, что инструменты тонки на земле. Однако существует следующее: https://github.com/NJsonSchema/NJsonSchema

Как вы, ребята, это делаете?

Интересно у меня был именно этот разговор с коллегой не 10 минут назад: р

Мы требуем отказа сборки (или приемочные испытания), если модель отклоняется от заранее определенной схеме.

Итак, вы можете сделать шаг в своей сборке, которая использует пакет NJsonSchema для создания схемы из вашей модели. Затем у вас есть шаг сравнения, который сравнивает выведенную схему с схемой документов API.

И, наоборот, вы можете сгенерировать код из своей схемы, а затем сравнить результат с моделями в своем выводе сборки.

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

Оставайтесь конечно, друг.