mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
6955f30257
* Document nested group support for AsyncAPI Generated-By: mintlify-agent * Apply suggestion from @ethanpalm --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
139 lines
3.2 KiB
Plaintext
139 lines
3.2 KiB
Plaintext
---
|
|
title: "AsyncAPI setup"
|
|
description: "Set up real-time WebSocket documentation using AsyncAPI specification files to generate interactive channel and message reference pages."
|
|
keywords: ["asyncapi", "websocket"]
|
|
---
|
|
|
|
## Demo
|
|
|
|
See the [WebSocket playground](/api-playground/websocket-playground) for an example of the AsyncAPI playground.
|
|
|
|
## Add an AsyncAPI specification file
|
|
|
|
To create pages for your WebSocket channels, you must have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0).
|
|
|
|
<Tip>
|
|
Use the [AsyncAPI Studio](https://studio.asyncapi.com/) to validate your AsyncAPI schema.
|
|
</Tip>
|
|
|
|
```json {3}
|
|
/your-project
|
|
|- docs.json
|
|
|- asyncapi.json
|
|
```
|
|
|
|
## Auto-populate WebSocket pages
|
|
|
|
To automatically generate pages for all channels in your AsyncAPI schema, add an `asyncapi` property to any navigation element. The `asyncapi` property accepts a path to an AsyncAPI schema document in your documentation repo, a URL to a hosted AsyncAPI document, or an array of links to AsyncAPI schema documents.
|
|
|
|
### Examples with tabs
|
|
|
|
<CodeGroup>
|
|
|
|
```json Local file
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API Reference",
|
|
"asyncapi": "/path/to/asyncapi.json"
|
|
}
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
```json Remote URL
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API Reference",
|
|
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
```json Multiple files
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API Reference",
|
|
"asyncapi": [
|
|
"/path/to/events.json",
|
|
"/path/to/webhooks.json"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
<Note>
|
|
When you specify multiple AsyncAPI files, each file generates its own set of channel pages.
|
|
</Note>
|
|
|
|
### Examples with groups
|
|
|
|
```json
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "AsyncAPI",
|
|
"groups": [
|
|
{
|
|
"group": "Websockets",
|
|
"asyncapi": {
|
|
"source": "/path/to/asyncapi.json",
|
|
"directory": "websockets"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
The `directory` field is optional. If not specified, Mintlify adds the files to the **api-reference** folder of the docs repository.
|
|
</Note>
|
|
|
|
### Examples with nested groups
|
|
|
|
The `asyncapi` property supports nested groups. Mintlify generates the channel pages and adds them to the nested group, alongside any existing pages.
|
|
|
|
This is useful when you want to organize WebSocket channels as a subsection of a broader API group, or when you need to combine multiple AsyncAPI specifications under a shared parent group.
|
|
|
|
```json
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API Reference",
|
|
"groups": [
|
|
{
|
|
"group": "Voice API",
|
|
"pages": [
|
|
"voice/overview",
|
|
{
|
|
"group": "Voice API Commands",
|
|
"asyncapi": "/path/to/voice-asyncapi.json"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Channel page
|
|
|
|
If you want more control over how you order your channels or if you want to reference only specific channels, create an MDX file with the `asyncapi` property in the frontmatter.
|
|
|
|
```mdx
|
|
---
|
|
title: "Websocket Channel"
|
|
asyncapi: "/path/to/asyncapi.json channelName"
|
|
---
|
|
```
|