AsyncAPI Publishing & Rendering
This design document describes the implementation of Async API 3.0 specification support and rendering in APIHUB Portal. The feature adds support for rendering Async API 3.0 specifications, with initial support limited to two protocols: Kafka and RabbitMQ (AMQP).
| Page/Functionality | Scope | Out of Scope |
| Overview Tab | ·Display AsyncAPI Operations | ·AsyncAPI Validation |
| API Operations Tab | ·Display AsyncAPI operations in operations list ·Filter by protocol (Kafka/AMQP) ·Display action badges (send/receive) ·Display protocol column ·Display custom metadata | |
| API Changes Tab | Out of scope | |
| Deprecated Tab | Out of scope | |
| API Quality | Out of scope | |
| Documents Tab | ·Display Document Overview Page ·Display Document Operation Page ·Support Export with File Formats(YAML/JSON) ·Support Export with AsyncAPI Extensions (Preserve/Remove Extensions) | ·Support Export with File Formats(Interactive HTML) ·Preview(stoplight) ·Copy Public link to source ·Copy page template |
| Package Settings | ·Support all Tabs(except API Specific Configuration) | ·API Specific Configuration(applicable only for REST API) |
| Global Search | ·Support "AsyncAPI" option to API type filter ·Search AsyncAPI operations | ·Advanced search filters specific to AsyncAPI(API specific params) |
| Description | Mockup | API | |
| 1 | Package Settings ·remove "API Specific Configuration" tab ·API Specific Configuration is not applicable to AsyncAPI specifications | [Figma link] | |
| 2 | Overview Tab → Summary ·add "AsyncAPI Operations" section ○Default order: 1. REST API Operations, 2. PgphQL Operations, 3. AsyncAPI Operations ·remove "Compare" button from header ·remove "AsyncAPI Validation" table ○Table shall not be displayed for AsyncAPI operation type | [Figma link] | |
| 3 | Overview Tab → Group → Create Manual Group ·add "AsyncAPI" option to "API Type" dropdown field ·User can select "AsyncAPI" when creating a new manual group for AsyncAPI operations | [Figma link] | |
| 4 | API Operations Tab • Update operations table columns for Async API (Name/Path, Protocol) • Add "Protocol" column to general filters | [Figma link] | |
| 5 | API Operations Tab → API Type Selector: • add "AsyncAPI" option to API type dropdown • Default order: 1. REST, 2. GraphQL, 3. AsyncAPI | [Figma link] | |
| 6 | Documents Tab: • add AsyncAPI document type with AsyncAPI icon | [Figma link] | |
| 7 | Documents Tab → Operations View: • add updated Operations View(Protocol column, new path) | [Figma link] | |
| 8 | Global Search: • add "AsyncAPI" option to API type filter ○ Default order: 1. REST, 2. GraphQL, 3. AsyncAPI | [Figma link] |
| Element Path | Type | Description | Usage in Rendering |
| MESSAGE PAYLOAD | |||
| message/payload | SchemaObject or any | JSON Schema for message payload | Main data schema for the message Analogous to Request Body in OpenAPI Render via JsonSchemaViewer |
| operations.{operationName}.message/payload | SchemaObject or any | Operation payload | Message payload for the operation |
| channels.{channelName}.messages.{messageName}.payload | SchemaObject or any | Channel message payload | Message payload in the channel |
| components/messages.{messageName}.payload | SchemaObject or any | Payload in message definition | Reusable payload |
| MESSAGE HEADERS | |||
| message Headers | SchemaObject or ReferenceObject | JSON Schema for message headers | Message headers schema Analogous to Request Headers in OpenAPI Render via JsonSchemaViewer |
| operations.{operationName}.message Headers | SchemaObject or ReferenceObject | Operation headers | Message headers for the operation |
| channels.{channelName}.messages.{messageName}.headers | SchemaObject or ReferenceObject | Channel message headers | Message headers in the channel |
| components/messages.{messageName}.headers | SchemaObject or ReferenceObject | Headers in message definition | Reusable headers |
| components.messageTraits.{traitName}.headers | SchemaObject or ReferenceObject | Headers from message trait | Headers from trait (applied to messages) |
| CHANNEL PARAMETERS | |||
| channels.{channelName}.parameters.{paramName}.schema | SchemaObject | JSON Schema for channel parameter | Channel parameter schema Analogous to Path Parameters in OpenAPI Render via JsonSchemaViewer |
| components.params.{paramName}.schema | SchemaObject | JSON Schema for parameter in components | Reusable parameter schema Render via JsonSchemaViewer |
| COMPONENTS SCHEMAS | |||
| components}schemas.{schemaName} | SchemaObject | Reusable JSON Schema | Reusable schemas Analogous to components.schemas in OpenAPI Render via JsonSchemaViewer ) |
prerequisite: All 11 custom extensions cannot be used simultaneously in one binding. They are divided into groups and depend on the channel type.
Key Point: The is Field in bindings.amqp
In AsyncAPI 3.0 for AMQP channel binding, there is a mandatory field that determines the channel type:
- is: queue
$\rightarrow$ channel is a queue (Queue) - is:routingKey
$\rightarrow$ channel is an exchange (Exchange)
This means that properties for queue and exchange are mutually exclusive - they cannot be used together in one channel.
All properties in this group can be used together in one channel with is: queue:
| # | Custom Extension | Format | Description |
| 1 | channels.<>.bindings.amqp.queue.x-dead-letter | boolean | Set to true for DLQ |
| 2 | channels.<>.bindings.amqp.queue.x-exported | boolean | BG functionality for exporting messages between RabbitMQ VHosts |
| 3 | channels.<>.bindings.amqp.queue.x-type | String | Queue type, e.g., quorum |
| 4 | channels.<>.bindings.amqp.queue.x-auto-delete | boolean | Auto-delete attribute for queue |
| 5 | channels.<>.bindings.amqp.queue.x-channel-bindings | Array of objects with the following fields: • channelAddress - mandatory •routingKey - optional | List of relations between RabbitMQ Queue's and Exchanges or between Exchanges only. Example: x-channel-bindings: - { channelAddress: "quote_state_change_exchange_v1", routingKey: "INProgress" } - { channelAddress: "some-exchange-name" } Note: • Here channelAddress is a source channel for the message routing and current channel is a destination. |
Example:
channels:
my-queue:
bindings:
amqp:
is: queue # ← determines this is a queue
queue:
x-dead-letter: true # can use
x-exported: true # can use
x-type: quorum # can use
x-auto-delete: false # can use
x-channel-bindings: [...] # can useAll properties in this group can be used together in one channel with is:routingKey:
| # | Custom Extension | Format | Description |
| 6 | channels.<>.bindings.amqp.exchange.x-dead-letter | boolean | Set to true for DLX |
| 7 | channels.<>.bindings.amqp.exchange.x-type | String | Exchange type: fanout, topic, or direct |
| 8 | channels.<>.bindings.amqp.exchange.x-auto-delete | boolean | Auto-delete attribute for exchange |
| 9 | channels.<>.bindings.amqp.exchange.x-exclusive | boolean | Exclusive attribute for exchange |
| 10 | channels.<>.bindings.amqp.exchange.x-channel-bindings | Array of objects with the following fields: • channelAddress - mandatory •routingKey - optional | List of relations between RabbitMQ Queue's and Exchanges or between Exchanges only. Example: x-channel-bindings: - { channelAddress: "quote_state_change_exchange_v1", routingKey: "INProgress" } - { channelAddress: "some-exchange-name" } |
| Note: • Here channelAddress is a source channel for the message routing and current channel is a destination. |
Example:
channels:
my-exchange:
bindings:
amqp:
is: routingKey # ← determines this is an exchange
exchange:
x-dead-letter: true # can use
x-type: fanout # can use
x-auto-delete: false # can use
x-exclusive: false # can use
x-channel-bindings: [...] # can use| # | Custom Extension | Format | Description |
| 11 | components/messages.<>.bindings.amqp.x-routing-key-source | String | Document what is used as routing-key when message is published. Example: quote.state |
Used in message definition and does not depend on channel type.
Example:
components:
messages:
MyMessage:
bindings:
amqp:
x-routing-key-source: "quote.state" # can use