Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/_help/continuous-integration/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions src/_help/getting-started/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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/).

Expand Down
70 changes: 56 additions & 14 deletions src/_help/specification-support/asyncapi-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,37 +5,78 @@ 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

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: 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`,
Comment thread
fbraure marked this conversation as resolved.
Resolved
- 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`

Expand All @@ -48,6 +89,7 @@ AsyncAPI `securitySchemes` property with these authentication types are supporte
- `openIdConnect`

The following authentication types are **not** supported:
- `userPassword`
- `X509`
- `symmetricEncryption`
- `asymmetricEncryption`
Expand All @@ -56,12 +98,12 @@ 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

JSON Schema provides the possibility to declare a property as read or write only. Read more in [the JSON Schema section of this documentation](/help/specification-support/json-schema#readonly-and-writeonly-properties).

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/).
6 changes: 3 additions & 3 deletions src/_help/specification-support/json-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}


Expand Down
Loading