The intersection of all things about spec HOT 2 CLOSED

/cc @olydis

from spec.

Hey @fearthecowboy!

Thanks for reaching out. What you're telling me sounds exciting. If I understand correctly, you want to come up with a schema that could unify both specifications, right? If that's the case, it shouldn't be hard if you start from AsyncAPI. I started by cloning OpenAPI and changing what was really needed. And I can tell you it wasn't that much.

AsyncAPI v2.0.0

I think it would be interesting for you to follow up the work I'm doing on the v2 branch. The README is not updated, but you can get a taste of what's coming by looking at https://github.com/asyncapi/asyncapi/tree/v2/test/docs.

This branch contains some breaking changes, breaking as in comparison with version 1 and OASv3. All of them are justified and have been approved after some people reported the need for them. Anyhow, it shouldn't differ very much from OASv3.

Response to provoking thought number one.

Adding an OASv3 path item object to AsyncAPI should be pretty straightforward. Topics and Paths share the same format. However, be aware that in AsyncAPI v2 a topic object will become an array of messages.

Response to provoking thought number two.

I have the same feeling. However, take into account that maintaining such schema alongside the evolution of OAS and AsyncAPI can be a pain, as both specs have different targets and very different problems to tackle.

Response to provoking thought number three.

I saw that you've also talked about supporting other "payload format definitions" and other such things. I'd like to understand what you're thinking of here.

In version 2, I'm already introducing a way to document non-JSON character sequences. They are very useful for documenting IoT APIs, where you receive a string of data formatted following a custom internal protocol. Check this example. It documents the Wolksense MQTT API.

I hope I understood correctly after all this text 😄.

Anyhow, let me know if I can help somehow. I'll be glad to do it.

from spec.