AsyncAPI Support

AsyncAPI is a specification for describing Event-Driven Architecture (EDA). Systems that can be described with AsyncAPI include Kafka, the various 'MQs (For example, RabbitMQ, ActiveMQ), MQTT, Websockets and so on.

AsyncAPI was influenced by OpenAPI in its structure, utilizing YAML (or JSON) and reusing 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 (For example, Avro).

AsyncAPI is an open source community, specification, and toolkit. For more information about the ecosystem, see AsyncAPI.com.

Important

Async API 3. x.x is currently in beta support. Some features are currently not available, such as:

Validation is disabled.
Documentation on hover redirects to AsyncAPI 2 instead of AsyncAPI 3.
No integrations are currently supported.

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 support GitLab/GitHub/BitBucket, and then only support the unresolved YAML/JSON as targets to sync to and from the SCMs.
Codegen, API Mocking for AsyncAPI APIs, Form editor, navigation panel, Open in Explore, and contract testing functionality are not supported.

Create AsyncAPI Definitions

Manually

When you create a new API, use the Specification option to select AsyncAPI 2.x.x or AsyncAPI 3.x.x. This choice also determines the available API templates.

When you import API definitions into Swagger Studio, 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 Swagger Studio 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 or asyncapi: 3.x.x.

You can recognize AsyncAPI definitions in the My APIs and other search results pages as they are displayed with the ASYNC tag.

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.