AsyncAPI Support

Last modified on November 28, 2022

AsyncAPI is a specification for describing Event-Driven Architecture (EDA). Systems that can be described with AsyncAPI include Kafka, the various 'MQs (e.g., RabbitMQ, ActiveMQ), MQTT and Websockets to name a few.

AsyncAPI was influenced by OpenAPI in the way it structures its definitions, using YAML (or JSON) and re-using the same structures found in OpenAPI, where possible. It makes use of JSON Schema for some of its model definitions and includes support for others (e.g., Avro).

AsyncAPI is an exciting open source community, specification and tool set. And we're happy to see its growth. For more information about the ecosystem, see AsyncAPI.com.

Considerations

Keep the following in mind when using AsyncAPI:

  • Interactive documentation is based on the open source project https://github.com/asyncapi/asyncapi-react. We endeavor to keep it as up-to-date as possible, but will lag behind the bleeding edge.

  • SCM/Git Integrations only supports GitLab/GitHub/BitBucket and then only supports the unresolved YAML/JSON as targets to sync to and from the SCMs.

  • There is no support for Codegen for AsyncAPI APIs.

  • There is no support for API Mocking for AsyncAPI APIs.

  • There is no support for Standardization for AsyncAPI APIs.

Create AsyncAPI 2.x Definitions

Manually

When you create a new API, use the Specification combo box to choose AsyncAPI-2.x.x. This choice also determines the available API templates. The only template currently available is the Streetlights template which is automatically applied whenever you create a new AsyncAPI API definition.

When you import API definitions into SwaggerHub, it will automatically determine the specification (and specification version) of the imported API definition.

Programmatically

You can also create and update API definitions programmatically, for example, using SwaggerHub CLI or Registry API.

curl -X POST "http(s)://SERVER/v1/apis/MyOrg/MyApi"
     -H "Authorization: YOUR_API_KEY"
     -H "Content-Type: application/yaml"
     --data-binary @./path/to/myapi.yaml

The specification will be automatically detected.

Converting AsyncAPI

It's not possible to convert between OpenAPI and AsyncAPI, as they're designed to describe different systems. It is possible to describe HTTP interactions with AsyncAPI but not recommended for describing full servers and clients.

How to tell if a definition is an AsyncAPI definition?

AsyncAPI specifications begin with asyncapi: 2.x.x.

You can recognize AsyncAPI 2.x definitions in the MY hub and other search results pages as they are displayed with the ASYNC2 badge.

To search for APIs that use the AsyncAPI specification, click on the search bar and choose AsyncAPI from the Specification pulldown so that only AsyncAPI APIs will be included in the search.

See Also

AsyncAPI How-To

Highlight search results