Как определить управляемую событиями архитектуру микросервисов с помощью спецификации OpenAPI/Swagger? Для событий важно документировать полезную нагрузку события, передаваемую между различными службами, даже если доступ к ним осуществляется не через HTTP-пути.
Все, что я видел, основано на API через HTTP-пути, поэтому мне интересно, как реализовать это с помощью спецификации OpenAPI / Swagger?
OpenAPI Spec 3.1 поддерживает события через свойство webhooks верхнего уровня. OpenAPI Spec 3.1 определяет поддержку веб-перехватчиков здесь:
Для инструментов, которые обрабатывают OAS 3.0, определение тел событий с использованием только схем по-прежнему полезно, поскольку такие определения могут использоваться инструментами codegen, такими как Генератор OpenAPI для автоматического создания объектов схемы для таких языков, как Java, Swift, Go и т. д.
Для Swagger Spec 2.0 (он же OpenAPI Spec 2.0) вы можете включить определения в спецификацию Swagger, как указано alamar. Swagger Codegen автоматически создаст классы моделей для этих определений, даже если они не связаны ни с какими путями. Я создаю и поддерживаю созданный Swagger Spec/Codegen SDK в Go для RingCentral API, который подобные события. Вы можете увидеть автоматически сгенерированные классы/структуры Swagger Codegen в следующей папке, отфильтровав 20 файлов, оканчивающихся на _event.go. В настоящее время они создаются с использованием swagger-codegen 2.3.1.
Если у вас есть несколько типов событий, наличие свойства события, которое может различать типы получаемых вами сообщений, может помочь проанализировать его в правильный класс/структуру события. В Go вы можете дважды демаршалировать данные: один раз в общую структуру для просмотра свойства типа события, а затем второй раз для фактического типа события.
Я также поддерживаю коллекцию примеров событий и кода синтаксического анализа в проекте преобразования веб-перехватчиков Chathooks, который вы можете использовать для справки. . Здесь вы можете увидеть примеры событий и (свернутые вручную) языковые определения:
В качестве альтернативы можно использовать AsyncAPI — спецификацию для архитектур, управляемых событиями. Он не зависит от протокола, поэтому его можно использовать с Kafka, Websocket, MQTT, AMQP и всем остальным, основанным на обмене сообщениями.
Я думаю, что у вас могут быть определения в Swagger, даже если они не используются никакими конечными точками. Просто объявите любые типы, которые вам нужны, в специальном разделе, например. «определения». Вы можете ссылаться на те, которые вы используете в конечных точках, например. "$ref": "#/definitions/User", в соответствии с основным живым примером Swagger.
Я ожидаю, что для них будет сгенерирован код, так что вы сможете написать тесты против любого из определений.
Если у вас есть строго типизированные события, вы можете использовать отражение для публикации структуры событий, и этого должно быть достаточно для клиента вашего микросервиса.
Если у вас есть дескрипторы событий (xml или аналогичные), используемые для регидрации событий из хранилища событий/журнала событий, вы можете опубликовать их.
В противном случае я не знаю никаких инструментов, которые работали бы как Swagger, но для событий.
Если вы используете Java, есть альтернатива. Я никогда не проверял это, но эта идея может помочь вам найти решение для других платформ.
Для этого вы можете использовать «хороший» и старый Javadoc и модуль Swagger из Enunciate, как описано здесь:
Вы можете сгенерировать swagger-ui из Javadoc с помощью Enunciate, в котором есть модуль Swagger.
Это просто плагин maven. В итоге у вас будет полная HTML-документация ваших сервисов, извлеченная из вашего Документы Java..
