Extending - support MQTT - question

[ghost]

Is it reasonable to write an extension that supports MQTT protocol in API definition?

It's required for IoT project, where both HTTP Rest and MQTT are primary protocols.

I need to generate nice looking documentation with SUBSCRIBE, PUBLISH etc, topic names, patters, json schemas. Looking similar to swagger generated documentation for REST services?

Does it even make sense?

[cbornet]

MQTT being a PUBLISH/SUBSCRIBE protocol, I don't think it fits well to an "API" description which describes a REQUEST/RESPONSE protocol.
In the IoT world, I think you could describe a CoAP API with OpenAPI.

[casualjim]

None the less publish subscribe is a very valid thing also for server sent events, websockets etc. imo OAI should support more than just request/response message flows because http already does more.

Something like this might work for it
#396

[ghost]

Generating documention works and looks good if I just replace GET/POST with PUBLISH/SUBSCRIBE , just gives some warnings.

It's probably not the way to go..

[lieldulev]

👍

I do think this issue is the same as #55 and #396.

[fehguy]

Parent issue #586

[gioppoluca]

+1 on this, is there anyone working on this?

[fehguy]

@gioppoluca I do not expect this will be part of 3.0, but it is in the list for future versions.

[akauppi]

Valid question and answers, got links, work ongoing in other issues. Can this one be closed?

[fmvilas]

@piotrmach you might be interested in the AsyncAPI specification: asyncapi.com. It's intended for the purpose you mentioned.

[xdvarpunen]

@fmvilas Asyncapi looks promising.

[fmvilas]

Thanks @xdvarpunen. We'll be launching version 2 soon. Stay tuned!

[AtosNicoS]

Is there any progress in this issue? Maybe the asyncapi project/ideas can be integrated into the openapi spec?

[fmvilas]

Hi @AtosNicoS. We've been discussing if and how to integrate both. So far, the only thing I can tell you is that it's going to take time, if ever happens.

In the meantime, let me know if I can help you with AsyncAPI. You can open an issue in our GitHub repo and/or join the Slack channel: https://async-apis-slack.herokuapp.com.

[fmvilas]

Sorry, I just saw you commented there. Keep the questions coming!

[AtosNicoS]

Now that I've tried asyncapi I must say that it is just great! I've looked through both specifications now, and I dont see that much problems of adding the asyncapi parts to the openapi spec.

@fmvilas Why not open a PR with the changes you made for asyncapi? This way we can track the differences between those two APIs better and avoid going too strong into different directions.

I think it would make a lot of sense to merge the two. Better now than later, when changes become even larger. It would also make the tooling more simple, as you dont need to rewrit everything for asyncapi, and rest and mqtt API do use similar styles.

[fmvilas]

We indeed had conversations about merging both, but the conclusion was that it would be a very bad idea, especially for tooling. Can you imagine yourself having to create a tool that will allow you to create/document/test/whatever HTTP APIs, MQTT APIs, WebSockets APIs, Kafka APIs, AMQP APIs, and a veeeery long etc?

We'll do our best to keep both in sync. Definitely @MikeRalphson is helping with that.

This is an old issue, and one of the reasons I started AsyncAPI.

[lornajane]

I'm going to add a strong recommendation for AsyncAPI and close this long-standing issue. I can't see us adding MQTT support into OpenAPI itself, but there are lots of people using and contributing to both projects and they will remain good sister standards!