AsyncAPI Publishing
Summary
Section titled “Summary”This design document describes the implementation of AsyncAPI 3.0 specification support and rendering in APIHUB Portal.
Assumptions
Section titled “Assumptions”- API Operation (AsyncAPI). For AsyncAPI, the term API Operation denotes the combination of three entities: channels, messages, and operations.
- API Changes tab and API Quality tab are out of scope for this document (handled by separate stories).
| Page / Functionality | Scope | Out of Scope |
|---|---|---|
| Overview Tab | • Summary • Activity history • Revision history |
• Groups |
| Operation Tab | • Filters • List of operations(Messages) • List view • Detailed view |
• Export operations to Excel |
| API Changes Tab | — | Out of Scope |
| Deprecated Tab | Same as in Operation Tab, but with deprecated badges (filters, list of deprecated operations, list view, detailed view). | • Export operations to Excel |
| API Quality Tab | — | Out of Scope |
| Documents Tab | • Overview tab • View operations tab • Export • Copy public link to source • Copy page template |
• Preview (Stoplight) • Export with extensions settings (preserve/remove extensions) |
Overview Tab
Section titled “Overview Tab”| Description | Mockups | API |
|---|---|---|
| Summary. If the user opens the Summary page, the system shall display a summary of the AsyncAPI package version, including: (1) total number of operations, (2) number of deprecated operations, (3) number of no-BWC operations. | ||
| Activity history. If the user opens the Activity history tab, the system shall provide the ability to view a list of actions performed by users on the current package. | ||
| Revision history. If the user opens the Revision history tab, the system shall provide the ability to view information about all revisions of the current package. |
API Operation (Messages) Tab
Section titled “API Operation (Messages) Tab”| Description | Mockups | API |
|---|---|---|
| Filters. If the user is on the API Operation (Messages) tab, the system shall display filters on the left sidebar. The filters shall consist of: • Filter by Audience • Filter by Protocol • Filter by API Kind • Filter by Channel Filter by Channel shall show a list of all channels in the current package version and shall allow the user to filter the list of messages by selected channel(s). If the user clicks the filter button (to the right of “Search operations”), the system shall collapse or expand the filters sidebar. |
||
| Main list of operations (messages) — List View. If the user is on the API Operation (Messages) tab, the system shall display the main list of all messages by default in List View. The table shall have the following columns: • Messages — Message title, operation action (send or receive), and channel address • Channel — the channel in which the message is defined • Protocol — the protocol used by the message in the channel • API Kind — the kind of the message (from extension; see extensions section below) • Audience — the audience of the message (from extension) |
||
| Main list of operations (messages) — Detailed View. If the user switches to Detailed View (via the Detailed View button), the system shall display the screen in two parts: • On the left — only the data from the Messages column (message title, operation action, and channel address) • On the right — the Doc View for the selected message The filters sidebar shall remain in place and unchanged. |
||
| Search operations. If the user enters text in the Search operations field, the system shall filter the list of messages by message name so that the user can find the required message. |
Deprecated Tab
Section titled “Deprecated Tab”| Description | Mockups | API |
|---|---|---|
| Filters. The system shall behave the same as described for the API Operation (Messages) tab: filters on the left sidebar (Filter by Audience, Filter by Protocol, Filter by API Kind, Filter by Channel), with the ability to collapse or expand the filters sidebar via the filter button. |
||
| Main list of API operations (messages). The system shall behave the same as described for the API Operation (Messages) tab (list of messages with table columns: Messages, Channel, Protocol, API Kind, Audience). If a message or channel is deprecated, the system shall display a yellow deprecated badge next to the message title or in the Channel column under the channel title, as defined in the Deprecated logic below. |
||
| Deprecated logic. In AsyncAPI 3.0 there is no native deprecated: true/false for channels and messages; it exists only for Schema Object and Operation Object. Deprecated state is expressed via extensions (see the list of extensions below).• Message deprecated. If the user marks a message as deprecated via the extension components.messages.<?>.x-deprecated, the entire message shall be treated as deprecated. The system shall display a yellow deprecated badge to the right of the message title.• Channel deprecated. If the user marks a channel as deprecated via the extension channels.<?>.x-deprecated, that channel and all messages within it shall be treated as deprecated. The system shall display a yellow deprecated badge in the Channel column, under the channel title only. The system shall not duplicate the deprecated badge on every message row that belongs to the deprecated channel. |
||
| Deprecated in Doc View. If the user opens a message and the message is deprecated, the system shall open Doc View and display a yellow deprecated badge to the right of the Message title in the Doc View header. |
Documents Tab
Section titled “Documents Tab”| Description | Mockups | API |
|---|---|---|
| List of documents. If the user selects the Documents tab, the system shall display a page consisting of a left sidebar and a main content area. The system shall display in the left sidebar a list of all documents in the current package version. AsyncAPI documents shall be shown with a specific purple icon. Above the list of documents, the system shall display a “Search” field. If the user enters text in Search, the system shall allow the user to search by name for documents in the current package version. |
||
| Overview tab view (default). By default, the main content area shall open in Overview tab view. The system shall display information from the selected AsyncAPI document taken from the specification info section: version, title, and description. If the user selects a different document from the list, the system shall update the main content area and display the overview for the newly selected document. |
||
| Operations tab view. If the user switches to the Operations tab view, the system shall display all operations (messages) for the document currently selected from the list. The structure of the messages table (columns: Messages, Channel, Protocol, API Kind, Audience) shall be the same as in the API Operation (Messages) tab. |
||
| More functionality. If the user clicks the “More” button, the system shall display additional options: • Export. If the user selects Export, the system shall open an export settings modal. The modal shall offer: – File format: JSON or YAML After the user selects the format and clicks Export, the system shall download the selected document locally. • Copy public link to source. The system shall provide the ability to copy the public link to the source. • Copy page template. The system shall provide the ability to copy the page template. |
Custom Properties (Extensions)
Section titled “Custom Properties (Extensions)”| Custom Property | Format | Mandatory | Description |
|---|---|---|---|
channels.<?>.x-api-kind |
String | no | Value: no-BWC. Mark that channel is not supported BWC policies |
channels.<?>.x-deprecated |
boolean | no | Mark that Channel as deprecated |
operations.<?>.x-api-kind |
String | no | Value: no-BWC. Mark that operation is not supported BWC policies |
channels.<?>.bindings.amqp.queue.x-dead-letter |
boolean | no | Set to true for DLQ |
channels.<?>.bindings.amqp.queue.x-exported |
boolean | no | BG functionality for exporting messages between RabbitMQ VHosts |
channels.<?>.bindings.amqp.exchange.x-exported |
boolean | no | BG functionality for exporting messages between RabbitMQ VHosts |
channels.<?>.bindings.amqp.queue.x-type |
String | no | quorum |
channels.<?>.bindings.amqp.exchange.x-dead-letter |
boolean | no | Set to true for DLX |
channels.<?>.bindings.amqp.queue.x-channel-bindings |
Array of objects with the following fields: • channelAddress - mandatory • routingKey - optional |
no | List of relations between RabbitMQ Queue’s and Exchanges or between Exchanges only. Example: yaml<br>x-channel-bindings:<br> - { channelAddress: "quote_state_change_exchange_v1", routingKey: "IN_PROGRESS" }<br> - { channelAddress: "some-exchange-name" }<br>Note: • Here channelAddress is a source channel for the message routing and current channel is a destination. |
channels.<?>.bindings.amqp.exchange.x-channel-bindings |
same as above | no | same as above |
components.<?>.messages.<?>.bindings.amqp.x-routing-key-source |
String | no | Document what is used as routing-key when message is published. Example: quote.state |
components.<?>.messages.<?>.x-deprecated |
boolean | no | Mark that Message as deprecated |