From 712be73299060d92fc85411c549b9caa3624516e Mon Sep 17 00:00:00 2001 From: grossyoan Date: Tue, 20 Oct 2026 12:56:51 +0200 Subject: [PATCH 1/2] help center: updates for AsyncAPI 3 help center/async3: update --- src/_help/continuous-integration/cli.md | 2 +- src/_help/getting-started/concepts.md | 4 +- .../specification-support/asyncapi-support.md | 67 +++++++++++++++---- .../specification-support/json-schema.md | 6 +- 4 files changed, 59 insertions(+), 20 deletions(-) diff --git a/src/_help/continuous-integration/cli.md b/src/_help/continuous-integration/cli.md index 8c89c545..984b6528 100644 --- a/src/_help/continuous-integration/cli.md +++ b/src/_help/continuous-integration/cli.md @@ -7,7 +7,7 @@ title: Bump CLI The Bump.sh CLI is used to interact with API documentation and hubs hosted on Bump.sh from your choice of popular API description formats: OpenAPI, Swagger, or AsyncAPI. -Using [OpenAPI](https://spec.openapis.org/) (v3.x and v2.0) or [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) (2.x), you can do any of the following: +Using [OpenAPI](https://spec.openapis.org/) (v3.x and v2.0) or [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) (2 and 3), you can do any of the following: - Validate an API document before publishing to your documentation. - Publish an API document to your Bump.sh documentation or hubs. diff --git a/src/_help/getting-started/concepts.md b/src/_help/getting-started/concepts.md index 8b2af064..bf2cedf2 100644 --- a/src/_help/getting-started/concepts.md +++ b/src/_help/getting-started/concepts.md @@ -19,7 +19,7 @@ Specifications are the official standards used to describe, among other things: - an API workflow (Flower, Arazzo, ...). These standards outline a set of elements and rules to follow when writing an API definition. -We support OpenAPI, AsyncAPI (up to 2.6), Flower (our own workflow specification) and Arazzo. To learn more about the supported specifications, we have written dedicated guides on [OpenAPI](/guides/openapi), [AsyncAPI](/guides/asyncapi/what-is-asyncapi/) and [Arazzo](/arazzo/v1.0/). We also made a guide on [Flower](/help/mcp-servers/specification-support/flower-support), our own workflow standard. +We support OpenAPI, AsyncAPI (2 and 3), Flower (our own workflow specification) and Arazzo. To learn more about the supported specifications, we have written dedicated guides on [OpenAPI](/guides/openapi), [AsyncAPI](/guides/asyncapi/what-is-asyncapi/) and [Arazzo](/arazzo/v1.0/). We also made a guide on [Flower](/help/mcp-servers/specification-support/flower-support), our own workflow standard. ### Deployment @@ -34,7 +34,7 @@ A deployment is the processing of an API or a workflow document by Bump.sh: afte An API definition is the representation of an API written in compliance with an existing specification. It is sometimes referred to as an API schema, API contract, or even [API specification](/help/getting-started/concepts/#specification) (which is something different). -As of today, Bump.sh supports the following specifications: [OpenAPI (Swagger)](https://spec.openapis.org/oas/latest.html), and [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/v3.0.0). +As of today, Bump.sh supports the following specifications: [OpenAPI (Swagger)](https://spec.openapis.org/oas/latest.html), and [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest). We provide a detailed introduction to API definitions [through this guide](/guides/api-basics/api-contracts-extended-introduction/). diff --git a/src/_help/specification-support/asyncapi-support.md b/src/_help/specification-support/asyncapi-support.md index f25718cc..607ac050 100644 --- a/src/_help/specification-support/asyncapi-support.md +++ b/src/_help/specification-support/asyncapi-support.md @@ -5,19 +5,20 @@ title: AsyncAPI Support - TOC {:toc} -We currently support [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/v2.6.0#messageObject) up to version 2.6. If you’re interested in support for version 3.0, feel free to reach out to us directly via [email](mailto:hello@bump.sh). This pages describes some specificities related to our support for this specification. +We support the [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/latest) versions 2 and 3. This page describes some specificities related to our support for this specification. ## Minimal mandatory fields Bump.sh needs to receive at least these fields to generate a Message-Driven documentation -| field | description | -|----------------|---------------------------------------------------------------------------| -| `asyncapi` | define which version of the specification you want to use. E.g. `"2.6.0"` | -| `info` | General information about your API | -| `info.title` | The title of the API | -| `info.version` | The version of the API document | -| `channels` | The available channels and messages for the API | +| field | description | +|----------------|---------------------------------------------------------------------------------------------------| +| `asyncapi` | define which version of the specification you want to use. E.g. `"3.1.0"` | +| `info` | General information about your API | +| `info.title` | The title of the API | +| `info.version` | The version of the API document | +| `channels` | AsyncAPI 2: the available channels and messages for the API | +| `operations` | AsyncAPI 3: the available operations for the API, each with an `action` and a `channel` `$ref` | ## Currently supported @@ -25,17 +26,54 @@ Bump.sh is able to extract: - root properties (AsyncAPI Object) - channels (with automatic grouping according to channel name or tag grouping) -- operations (subscribe and publish) +- operations (`subscribe` and `publish` in AsyncAPI 2, `send` and `receive` in AsyncAPI 3) - messages (payload and headers), with examples. -- bindings (server, operation and message). +- bindings (server, channel, operation and message). ## Customizing the navigation -By default, channels are displayed under a “Channels” section. You can replace it with your own set of sections using the [`x-tagGroups` vendor extension](/help/customization-options/sections/), which groups your tagged channels under the section names of your choice. +By default, operations are displayed under a “Channels” section in AsyncAPI 2, and under an “Operations” section in AsyncAPI 3. You can replace it with your own set of sections using the [`x-tagGroups` vendor extension](/help/customization-options/sections/), which groups your tagged operations under the section names of your choice. + +## AsyncAPI 3 + +> New to AsyncAPI 3? Read our [AsyncAPI cheat sheet](/guides/asyncapi/cheatsheet/). +{: .info} + +AsyncAPI 3 is supported. To use it, set the version in your API document: + +```yaml +asyncapi: "3.1.0" +``` + +The features introduced by this version are handled as follows: + +| Feature | Bump.sh behaviour | +|---------|-------------------| +| Operation object: `action` | Displayed as a `send` or `receive` badge on the operation. | +| Operation object: `channel` | The operation displays the address, description, parameters and bindings of its channel. An operation without a valid `channel` is ignored. | +| Operation object: `messages` | Displayed on the operation. When an operation lists no `messages`, all the messages of its channel are displayed. | +| Operation object: `reply` | Displayed in a "Reply" block below the operation, showing the reply's address, messages, parameters and bindings. | +| Operation Reply Address object | Its `location` is displayed as the reply address, instead of the reply channel address. | +| Channel object: `address` | Displayed as the path of the operation. A channel without an `address` is displayed as `{dynamicAddress}`. | +| Channel and Server objects: `title` and `summary` | Displayed alongside their description. | +| Operation object: `title` and `summary` | The `title` is used as the operation title. When an operation has no `title`, its `summary` is used instead, and then its id. | +| Parameter object | Its `description`, `enum`, `default` and first item of `examples` are displayed. `location` is not displayed. | +| Server object: `host`, `pathname` and `protocol` | Used to build the server URL. Server variables are replaced by their default value. | +| Operation and Message traits | Applied following AsyncAPI 3 rules: a trait never overrides a value already defined on its target. | +| `info.tags` | Used to build the navigation. Root `tags` are used when `info.tags` is missing. | +| `externalDocs` | Displayed for the `info` object, servers, channels, operations and messages. | +| Security Scheme object: `scopes` and OAuth Flow object: `availableScopes` | Displayed in the Authentication section. Security requirements are read from the first server. | +| ROS 2 bindings (AsyncAPI 3.1) | Displayed for servers and operations. | + +The following fields are not supported yet: +- Message object: `correlationId`, `contentType`, and root `defaultContentType`, +- Message object: Multi Format Schema `payload` (`schemaFormat` and `schema`): the payload is not displayed, +- Operation object: `security`, +- Channel object: `servers`. ## Partially supported: message object `payload` -[Message object](https://www.asyncapi.com/docs/reference/specification/v2.6.0#messageObject) field `payload` could be of any type according to the specification, but we only support `SchemaObject` type. +[Message object](https://www.asyncapi.com/docs/reference/specification/latest#messageObject) field `payload` could be of any type according to the specification, but we only support `SchemaObject` type. A payload of another type is not displayed. ## Partially supported: server `security` and `securitySchemes` @@ -48,6 +86,7 @@ AsyncAPI `securitySchemes` property with these authentication types are supporte - `openIdConnect` The following authentication types are **not** supported: +- `userPassword` - `X509` - `symmetricEncryption` - `asymmetricEncryption` @@ -56,7 +95,7 @@ The following authentication types are **not** supported: - `scramSha512` - `gssapi` -To describe these authentication types, please use our [custom `x-topics` property](/help/enhance-documentation-content/topics/) for now. +To describe these authentication types, please use our [custom `x-topics` property](/help/documentation-experience/topics/) for now. ## readOnly and writeOnly properties @@ -64,4 +103,4 @@ JSON Schema provides the possibility to declare a property as read or write only You can add extra information to your documentation by using Bump.sh custom `x-topics`. -Read more in the [Topics section of this documentation](/help/enhance-documentation-content/topics). +Read more in the [Topics section of this documentation](/help/documentation-experience/topics/). diff --git a/src/_help/specification-support/json-schema.md b/src/_help/specification-support/json-schema.md index 881bf03f..b5a27f3d 100644 --- a/src/_help/specification-support/json-schema.md +++ b/src/_help/specification-support/json-schema.md @@ -52,12 +52,12 @@ Thus, it becomes easy to use the same `Schema Object` in different contexts, for } ``` -> - `writeOnly` properties **are hidden** when they belong to a `subscribe` operation in AsyncAPI or a `response` in OpenAPI. +> - `writeOnly` properties **are hidden** when they belong to a `subscribe` operation in AsyncAPI 2, a `receive` operation in AsyncAPI 3, or a `response` in OpenAPI. > -> - `readOnly` properties **are hidden** when they belong to a `publish` operation in AsyncAPI or a `request` in OpenAPI. +> - `readOnly` properties **are hidden** when they belong to a `publish` operation in AsyncAPI 2, a `send` operation in AsyncAPI 3, or a `request` in OpenAPI. {: .warning} -> Not displaying `writeOnly` properties in subscribe operations and `readOnly` properties in publish operations allows the use of the same `Schema Object` everywhere it is needed, without documenting confusing/irrelevant properties in the wrong context. +> Not displaying `writeOnly` properties in subscribe and receive operations, and `readOnly` properties in publish and send operations, allows the use of the same `Schema Object` everywhere it is needed, without documenting confusing/irrelevant properties in the wrong context. {: .info} From 8ee7d355b07820dde301a97803979cc31888daea Mon Sep 17 00:00:00 2001 From: "Paul B." Date: Tue, 27 Oct 2026 10:00:25 +0100 Subject: [PATCH 2/2] help center: details about `schemaFormat` --- src/_help/specification-support/asyncapi-support.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/_help/specification-support/asyncapi-support.md b/src/_help/specification-support/asyncapi-support.md index 607ac050..bf99f0c9 100644 --- a/src/_help/specification-support/asyncapi-support.md +++ b/src/_help/specification-support/asyncapi-support.md @@ -67,7 +67,10 @@ The features introduced by this version are handled as follows: The following fields are not supported yet: - Message object: `correlationId`, `contentType`, and root `defaultContentType`, -- Message object: Multi Format Schema `payload` (`schemaFormat` and `schema`): the payload is not displayed, +- Message object: Partial support of Multi Format Schema `payload` and + `headers` (`schemaFormat` and `schema`). We only support it when + `schemaFormat` is AsyncAPI Schema objects, OpenAPI schema objects or + JSONSchema objects, - Operation object: `security`, - Channel object: `servers`.