Как-то я несколько озадачен текущей ситуацией со спецификациями OpenAPI / AsyncAPI

С одной стороны - все запросы на поддержку MQTT и прочих вариантов транспорта в OpenAPI закрываются со словами "не очень понятно, как это сделать, юзайте AsyncAPI" - https://github.com/OAI/OpenAPI-Specification/issues/553#issuecomment-620477276

С другой стороны - AsyncAPI стемится быть настолько generic, чтобы дать возможность описать все, что угодно - в том числе и HTTP. Однако, настолько широкая специализация делает ее слишком вербозной и недостаточно удобной для написания руками - https://github.com/OAI/OpenAPI-Specification/issues/55#issuecomment-1052572818

Казалось бы - проблемы нет? Пишем AsyncAPI спеку на асинхронные сервисы и OpenAPI - на HTTP. Но все упирается в то, что HTTP сервисы часто имеют поддержку SSE / Websockets, которую сейчас нельзя выразить в рамках OpenAPI (и не предвидится возможным). В итоге, чтобы описать один сервис, нам нужно иметь сразу две спецификации? - звучит сомнительно.

У автора AsyncAPI есть видение - он предлагает ссылаться из AsyncAPI прямо на OpenAPI - https://github.com/OAI/OpenAPI-Specification/issues/55#issuecomment-1057220490

Как будто бы это единственный вариант, но насколько он рабочий?

В моем представлении, если мы хотим максимально полное описание нашего сервиса в спецификации - нужно юзать AsyncAPI . C Code-first инструментами (типа FastStream) тут даже нет проблемы - их вербозность никак не мешает сгенерировать валидную спеку из кода, которая красиво отрисуется в HTML. А что делать Specification-first страдальцам? Писать руками AsyncAPI для HTTP - сомнительное удовольствие...

Я еще поиграюсь с тем, как работают референсы из AsyncAPI на OpenAPI - в этом может быть ответ, но пока будущее спецификаций туманно