Repository navigation
Product update: AsyncAPI 3 #505
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| title: "AsyncAPI 3 support" | ||
| tags: [New] | ||
| image: /docs/images/changelog/asyncapi-3-support.png | ||
| --- | ||
|
|
||
|  | ||
|
|
||
| AsyncAPI 3 changed the way event-driven APIs are described: operations are no longer nested in channels, `send` and `receive` replace the ambiguous `publish` and `subscribe`, request/reply becomes a first-class pattern, and channels and servers get a clearer structure. Bump.sh now supports AsyncAPI 3 documents: deploy them the same way as your other API documents. | ||
|
|
||
| If you didn't explore this version yet, our [AsyncAPI 3 cheat sheet](/guides/asyncapi/cheatsheet/) is a good place to start. | ||
|
|
||
| ## Operations first | ||
|
|
||
| In AsyncAPI 3, operations are declared on their own and point to a channel. Your documentation follows the same logic: each operation is listed in an "Operations" section, with a `send` or `receive` badge telling your users at a glance whether your application sends or receives the message. | ||
|
|
||
| ```yaml | ||
| channels: | ||
| tripQuoteRequests: | ||
| address: trips.quotes.requests | ||
| description: Quote requests sent by clients to the pricing service. | ||
| messages: | ||
| tripQuoteRequested: | ||
| $ref: '#/components/messages/TripQuoteRequested' | ||
|
|
||
| operations: | ||
| requestTripQuote: | ||
| action: send | ||
| title: Request a trip quote | ||
| channel: | ||
| $ref: '#/channels/tripQuoteRequests' | ||
| messages: | ||
| - $ref: '#/channels/tripQuoteRequests/messages/tripQuoteRequested' | ||
| ``` | ||
|
|
||
|  | ||
|
|
||
| Operations are grouped by tag, or by channel name when they have no tags. All the usual [navigation options](/help/customization-options/operations-navigation/) remain available, including [`x-tagGroups`](/help/customization-options/sections/). | ||
|
fbraure marked this conversation as resolved.
Resolved
|
||
|
|
||
| ## Operation replies | ||
|
|
||
| Many event-driven APIs expect an answer: a client sends a request on a channel and waits for the reply on another one. AsyncAPI 3 describes this pattern natively by adding a `reply` to the operation. | ||
|
|
||
| ```yaml | ||
| operations: | ||
| requestTripQuote: | ||
| action: send | ||
| channel: | ||
| $ref: '#/channels/tripQuoteRequests' | ||
| reply: | ||
| channel: | ||
| $ref: '#/channels/tripQuoteReplies' | ||
| messages: | ||
| - $ref: '#/channels/tripQuoteReplies/messages/tripQuote' | ||
| ``` | ||
|
|
||
| Your documentation now displays this reply: a new "Reply" block appears right below the operation, with the reply direction, its address, its messages, its parameters and its bindings. The request and its expected answer are documented side by side. | ||
|
grossyoan marked this conversation as resolved.
Resolved
|
||
|
|
||
|  | ||
|
|
||
| ## And more | ||
|
|
||
| - **Runtime addresses**: a channel without an `address` is displayed as `{dynamicAddress}`, and a reply `address.location` (e.g. `$message.header#/replyTo`) is displayed instead of the reply channel address. | ||
| - **Channel messages**: when an operation lists no `messages`, all the messages of its channel are displayed. | ||
| - **`title` and `summary`**: displayed for channels and servers. Operations use their `title`, or their `summary` when no title is set. | ||
| - **Servers**: their URL is built from `protocol`, `host` and `pathname`. | ||
| - **Traits**: operation and message traits are applied following AsyncAPI 3 rules, where a trait never overrides a value already defined on its target. | ||
| - **External docs**: on the `info` object, servers, operations, channels and messages. | ||
| - **OAuth 2 `availableScopes`**: displayed for each flow, with the scopes required by a security scheme. | ||
|
|
||
| The full list of supported fields, and those not supported yet, is available in the [help center](/help/specification-support/asyncapi-support/#asyncapi-3). | ||
|
|
||
| Questions or feedback about AsyncAPI 3? Write to us at [hello@bump.sh](mailto:hello@bump.sh). | ||
|
grossyoan marked this conversation as resolved.
Resolved
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
|
grossyoan marked this conversation as resolved.
Resolved
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.