AsyncAPI Publishing

Summary:

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).

Scope:

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 File Formats(Interactive HTML) Support Export with AsyncAPI Extensions (Preserve/Remove Extensions) 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:

Support AsyncAPI in Package Version Tabs

	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]

Rendering AsyncAPI in DocView

AsyncAPI 3.0 vs OpenAPI 3.0

AsyncAPI 3.0 Elements Using JSON Schema

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 )

Asyncapi Properties in JSON Schema

Keyword	Category	Description
title	Metadata	Human-readable name of the schema
type	Core	Defines the data type (string, object, array, etc.)
required	Object	List of required object properties
multipleOf	Number	Value must be a multiple of this number
maximum	Number	Maximum value (inclusive)
exclusiveMaximum	Number	Maximum value (exclusive)
minimum	Number	Minimum value (inclusive)
exclusiveMinimum	Number	Minimum value (exclusive)
maxLength	String	Maximum allowed string length
minLength	String	Minimum allowed string length
pattern	String	Regex pattern (ECMA-262) the string must match
maxItems	Array	Maximum number of array elements
minItems	Array	Minimum number of array elements
uniqueItems	Array	All array elements must be unique
maxProperties	Object	Maximum number of object properties
minProperties	Object	Minimum number of object properties
enum	Core	Allowed set of exact values
const	Core	Value must exactly equal the specified value
examples	Metadata	Array of example values
if	Conditional	Conditional schema: “if” branch
then	Conditional	Applied when if condition matches
else	Conditional	Applied when if condition does not match
readOnly	Metadata	Value is only used for reading (ignored in requests)
writeOnly	Metadata	Value is only used for writing (ignored in responses)
properties	Object	Named schemas for object properties
patternProperties	Object	Properties that match a regex key
additionalProperties	Object	Schema or boolean for extra, unspecified properties
additionalItems	Array	Schema/boolean for array items beyond items (tuple validation)
items	Array / Schema	Schema for array elements or tuple schemas
propertyNames	Object	Constraints applied to the names of object properties
contains	Array	Array must contain at least one item matching the schema
allOf	Composition	Must satisfy all listed schemas (logical AND)
oneOf	Composition	Must satisfy exactly one schema
anyOf	Composition	Must satisfy at least one schema
not	Composition	Must NOT satisfy the schema

Difference between OpenAPI

AsyncAPI-specific keyword	Exists in JSON Schema?	Exists in OpenAPI 3.1?
discriminator	✖	✔ (semantics differ in OAS 3.0 but fully compatible in 3.1)
externalDocs	✖	✔
deprecated	✖	✔
x-* extensions	Partially	✔

Custom Extensions for RabbitMQ(ampq)

prerequisite: All 11 custom extensions cannot be used simultaneously in one binding. They are divided into groups and depend on the channel type.

Usage Structure

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.

Custom Extensions Groups

Group 1: Queue Properties (used only if is: queue)

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 use

Group 2: Exchange Properties (used only if is:routingKey)

All 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

Group 3: Message Properties (independent of channel type)

#	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

Endpoints Changed for AsyncAPI Support

This document lists all API endpoints that were updated to support AsyncAPI 3.0 as a new API type. All endpoints that use the {apiType} path parameter now accept asyncapi as a valid value.

Operations Endpoints

1. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/operations

• Summary: Get list of operations
• Operation ID: getPackagesIdVersionsIdApiTypeOperations
• Changes:
  • {apiType} parameter now accepts asyncapi
  • Response schema updated to include AsyncAPIOperation in the oneOf list
• Description: Full list of operations without grouping by parent specification document. The result list depends on the API type.

2. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/operations/{operationId}

• Summary: Get operation details
• Operation ID: getPackagesIdVersionsIdApiTypeOperationsId
• Changes:
  • {apiType} parameter now accepts asyncapi
  • Response schema updated to include AsyncAPIOperation in the oneOf list
• Description: Operation's parameters and data. The result depends on the API type.

3. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/operations/{operationId}/changes

• Summary: Single operation change log
• Operation ID: getPackagesIdVersionsApiTypeOperationsIdChanges
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get changes of one operation between current and previous published package version. The result depends on the API type.

4. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/operations/{operationId}/deprecatedItems

• Summary: Deprecated items of single operation
• Operation ID: getPackagesIdVersionsApiTypeOperationsIddeprecatedItems
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get list of all deprecated items inside of the single operation.

5. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/operations/{operationId}/models/{modelName}/usages

• Summary: List of operations with the same model
• Operation ID: getPackagesIdVersionsApiTypeOperationsIdModelsModelName
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get list of operations that have the same model.

Deprecated Operations Endpoints

6. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/deprecated

• Summary: Get list of deprecated operations
• Operation ID: getPackagesIdVersionsIdApiTypeDeprecations
• Changes:
  • {apiType} parameter now accepts asyncapi
  • Response schema updated to include AsyncAPIOperationMeta in the oneOf list
• Description: List of deprecated operations in the current version.

Export Endpoints

7. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/export/operations

• Summary: Export operations to xlsx file
• Operation ID: getPackagesIdVersionsIdApiTypeOperationsExport
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Export operations of specific API type.

8. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/export/operations/deprecated

• Summary: Export deprecated operations to xlsx file
• Operation ID: getPackagesIdVersionsIdApiTypeDeprecatedOperationsExport
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Export operations of specific API type.

9. GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/changes

• Summary: Export changes to xlsx file
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Export changes between two compared package versions.

Changes/Changelog Endpoints

10. GET /api/v4/packages/{packageId}/versions/{version}/{apiType}/changes

• Summary: Get list of changed operations
• Operation ID: getPackagesIdVersionsIdApiTypeChangesV4
• Changes:
  • {apiType} parameter now accepts asyncapi
  • Response schema updated to include AsyncAPIOperationInfoFromDifferentVersions in the oneOf list for version comparison
• Description: Get changes between two compared package versions with details by operations. The result list depends on the API type.

Tags Endpoints

11. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/tags

• Summary: Get list of operations tags
• Operation ID: getPackagesIdVersionsIdApiTypeTags
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get list of operations tags in one published version. The result list depends on the API type.

Operation Groups Endpoints

12. POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups

• Summary: Create manual operation group
• Operation ID: PostPackageIdVersionApiTypeGroupsV3
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Create manual operation group. Manual groups can be created for both packages and dashboards. One group can contain operations of one API type only.

13. GET /api/v2/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}

• Summary: Get list of operations for operation group
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get list of operations from operation group. The result list depends on the API type.

14. PATCH /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}

• Summary: Update parameters of operation group
• Operation ID: patchPackageIdVersionApiTypeGroupName
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Update parameters of operations group.

15. GET /api/v1/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/template

• Summary: Get export template of operation group
• Operation ID: getPackageIdVersionApiTypeGroupNameTemplate
• Changes:
  • {apiType} parameter now accepts asyncapi
• Note: This feature is currently supported only for apiType = rest, but the parameter now accepts asyncapi for future compatibility.

16. GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents

• Summary: Get list of documents for operation group
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get list of documents for operation group.

17. POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/publish

• Summary: Publish operation group
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Publish operation group.

18. GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/publish/{publishId}/status

• Summary: Get publish status
• Changes:
  • {apiType} parameter now accepts asyncapi
• Description: Get status of publish operation.

Build/Export Group Endpoints

19. POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/build/groups/{groupName}/buildType/{buildType}

• Summary: Async document transformation
• Changes:
  • {apiType} parameter now accepts asyncapi
• Note: Document transformation is currently available only for apiType = REST, but the parameter now accepts asyncapi for future compatibility.
• Description: Async task for document transformation. Document transformation is required for exporting operations group.

20. GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType}

• Summary: Get export file
• Changes:
  • {apiType} parameter now accepts asyncapi
• Note: Export is currently available only for apiType = REST, but the parameter now accepts asyncapi for future compatibility.
• Description: Get export file for operation group.

Summary

Total Endpoints Changed: 20

All endpoints that use the {apiType} path parameter now accept asyncapi as a valid value alongside rest, graphql, and protobuf. The response schemas for operation-related endpoints have been updated to include AsyncAPI-specific schemas:

• AsyncAPIOperation - for operation details
• AsyncAPIOperationMeta - for operation metadata (action, channel, protocol, tags)
• AsyncAPIOperationInfoFromDifferentVersions - for version comparison

Note: Some endpoints (like template export and build/export group operations) currently have functional limitations that restrict them to REST API type only, but the parameter validation has been updated to accept asyncapi for future compatibility.