POC TypeSpec to AsyncAPI

[mikekistler]

AsyncAPI is a sister specification to OpenAPI for describing asynchronous (e.g. message queuing) APIs. AsyncAPI is gaining some traction in the industry and by producing an emitter for this we could demonstrate the flexibility and power of TypeSpec in another API domain.

[allenjzhang]

Backlog

[SnakeDoc]

This feature would make TypeSpec a "do-all" tool for those writing OpenAPI and AsyncAPI specs. It's not uncommon to have both within a single system.

Adding my support for this feature! 👍

[kennethaasan]

I agree with the above. At Sportradar we use both OpenAPI and AsyncAPI with JSON Schema and would consider TypeSpec if AsyncAPI was supported.

[sandrolain]

I'm considering using typespec, but at the moment I'm mostly working on event driven architectures. Support for the generation of specifications for asynchronous APIs and event schemas, such as AsyncAPI and cloudevents, would also be fantastic.

[bterlson]

Folks chiming in for AsyncAPI support, please feel free to link your AsyncAPI specs if they are public, it would be great to take a look!

[chiodonia]

@swisspost we designed hundreds of APIs (both REST and Streaming) using https://github.com/swisspost/apikana. Found TypeSpec very interesting but still missing the support for AsyncAPI

[SnakeDoc]

Folks chiming in for AsyncAPI support, please feel free to link your AsyncAPI specs if they are public, it would be great to take a look!

I don't have a public spec to offer at the moment - however the AsyncAPI team does maintain example specs in their repos for testing, such as this - just note the v3 directory contains AsyncAPI 3.x spec examples.

You may also be interested in these two discussions: #141 and #151, which showcase some 3.x spec examples and expected outputs from the validation/bundling process.

[creatorrr]

any updates on this @bterlson ?

[bterlson]

Nothing new to share, unfortunately. Keep chiming in with support, though!

[SnakeDoc]

I'm chiming in with support! ;)

[aeworxet]

There are official examples in https://github.com/asyncapi/spec/tree/master/examples, and you can view an example for nearly any version of the AsyncAPI Specification:

$ git tag

1.1.0
1.2.0
2.0.0
...
v2.0.0
v2.1.0
...
v2.4.0
v2.4.0-2022-04-release.1
...
v2.5.0-next-spec.5
v2.6.0
v3.0.0
v3.0.0-next-major-spec.1
...

There is also a separate repository, which provides all the JSON Schema documents for validating AsyncAPI documents.
https://github.com/asyncapi/spec-json-schemas

[Kreash]

I'm waiting for support, I really need it

[LievenMasschelein-code]

Hi , we are also using both openapi and asyncapi ! asyncapi support in typespec would really make it a valid case to use typespec !
I'm chimming in with support @bterlson

[mario-guerra]

We would like to support AsyncAPI but representing AsyncAPI with TypeSpec is challenging and will take some time to figure out.

It would help us to know how you would use AsyncAPI in practice. @LievenMasschelein-code @Kreash @chiodonia @SnakeDoc @kennethaasan @sandrolain @aeworxet

[aeworxet]

@mario-guerra

You can join AsyncAPI Slack Workspace and ask your questions in the channel

# 03_specification
4,403 members
All around the spec discussions. It is ok to ask for support here.

[SnakeDoc]

@mario-guerra Pretty much exactly the same way we use OpenAPI - our AsyncAPI spec is our "source of truth" for describing how our services should interact within our EDA.

I would guess one of the reasons you are not receiving many public AsyncAPI specs to look at is EDA/Message Broker stuff is often used internally.

That said, @aeworxet is a significant contributor to the AsyncAPI project and is a tremendous asset to have available for questioning! 🚀

[LievenMasschelein-code]

Hi for us also , just alike @SnakeDoc mentions, we use in the same way we use Openapi. For us Asyncapi is the only source of truth for our internal domain events between our microservices, we are building some automation on top of Asyncapi to have data quality checks for events and messages ingested in our data lakehouse platform. Asyncapi is also used to add events schema's in our confluent cloud ( kafka) schema registry and then to enforce them.

[aeworxet]

@aeworxet is a significant contributor to the AsyncAPI project and is a tremendous asset

😊

@fmvilas is the Founder of AsyncAPI, and @derberg is the Executive Director of AsyncAPI, so they are much more tremendous assets for asking questions. 🙂

[chiodonia]

Hi, we at SwissPost have been developing https://github.com/swisspost/apikana which is similar to TypeSpec.
Apikana has been used to design hundreds of REST and Stream APIs (Kafka and MQTT).

We are now willing to adopt asyncAPI for our stream APIs and are considering generating asyncAPI with Apikana. Since Apikana needs some investments we are also considering TypeSpec and are very interested in asyncAPI PoC.

From a stream API design point of view, we need to define the following asyncAPI elements:

• Info with additional x- fields
• Channels (topic name) with additional x- fields
• Messages and payloads (Json schema)
• Operations

I guess bindings, and other serialization formats (Protobuf,...) could be added later after the PoC.

AsyncAPI Servers and other elements are probably not relevant during the API design phase. The generated asyncAPI descriptors could be enriched with those elements when topics are deployed.

Andrea

[TertiumOrganum1]

Yes, very interested in asyncapi support too! Especially ver 3.0,which is much clearer and richer than 2.x.

[SnakeDoc]

Can anyone at Microsoft give us a hint if this is being worked on? The demand for this feature is here! A little extra transparency about status and ETA would be much appreciated.