Skip to content

Commit 4ec6818

Browse files
lawrekahahnbeelee
lawreka
and
hahnbeelee
authored
Asyncapi Docs (#629)
* add page about asyncapi setup * add playground page * update docs * add single channel page docs * delete unneeded paragraph * add local+remote * Update api-playground/asyncapi/setup.mdx Co-authored-by: Hahnbee Lee <[email protected]> * add asyncapi playground --------- Co-authored-by: Hahnbee Lee <[email protected]>
1 parent e1cdf6a commit 4ec6818

File tree

4 files changed

+177
-0
lines changed

4 files changed

+177
-0
lines changed

‎api-playground/asyncapi/playground.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Playground"
3+
description: "Enable users to interact with your websockets"
4+
asyncapi: "/asyncapi.yaml channelOne"
5+
---

‎api-playground/asyncapi/setup.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: "AsyncAPI Setup"
3+
description: "Create websocket reference pages with AsyncAPI"
4+
---
5+
6+
## Add an AsyncAPI specification file
7+
8+
To begin to create pages for your websockets, make sure you have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0). Your schema must follow the AsyncAPI specification 3.0+.
9+
10+
<Tip>
11+
To make sure your AsyncAPI schema is valid, you can paste it into the
12+
[AsyncAPI Studio](https://studio.asyncapi.com/)
13+
</Tip>
14+
15+
## Auto-populate websockets pages
16+
17+
You can add an `asyncapi` field to any tab or group in the navigation of your `docs.json`. This field can contain either the path to an AsyncAPI schema document in your docs repo, the URL of a hosted AsyncAPI schema document, or an array of links to AsyncAPI schema documents. Mintlify will automatically generate a page for each AsyncAPI websocket channel.
18+
19+
**Examples with Tabs:**
20+
21+
<CodeGroup>
22+
23+
```json Local File {5}
24+
"navigation": {
25+
"tabs": [
26+
{
27+
"tab": "API Reference",
28+
"asyncapi": "/path/to/asyncapi.json"
29+
}
30+
]
31+
}
32+
33+
```
34+
35+
```json Remote URL {5}
36+
"navigation": {
37+
"tabs": [
38+
{
39+
"tab": "API Reference",
40+
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
41+
}
42+
]
43+
}
44+
```
45+
46+
</CodeGroup>
47+
48+
**Examples with Groups:**
49+
50+
```json {8-11}
51+
"navigation": {
52+
"tabs": [
53+
{
54+
"tab": "AsyncAPI",
55+
"groups": [
56+
{
57+
"group": "Websockets",
58+
"asyncapi": {
59+
"source": "/path/to/asyncapi.json",
60+
"directory": "api-reference"
61+
}
62+
}
63+
]
64+
}
65+
]
66+
}
67+
```
68+
69+
<Note>
70+
The directory field is optional. If not specified, the files will be placed in
71+
the **api-reference** folder of the docs repo.
72+
</Note>
73+
74+
## Channel Page
75+
76+
If you want more control over how you order your channels or if you want to just reference a single channel, you can create an MDX file with the `asyncapi` field in the frontmatter.
77+
78+
```mdx
79+
---
80+
title: "Websocket Channel"
81+
asyncapi: "/path/to/asyncapi.json channelName"
82+
---
83+
```

‎asyncapi.yaml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
asyncapi: 3.0.0
2+
info:
3+
title: Test websocket schema
4+
version: 1.0.0
5+
description: This is a test websocket API.
6+
channels:
7+
channelOne:
8+
title: Test channel
9+
description: >-
10+
This is a websocket channel.
11+
12+
It can have _markdown_ in the description.
13+
14+
* Use the "echo-websocket.hoppscotch.io" server to receive timestamped messages every second.
15+
16+
* Use the "echo.websocket.org" server to send test messages to the websocket. This server will echo back any messages you send to it.
17+
18+
address: /
19+
messages:
20+
TestMessage:
21+
$ref: '#/components/messages/TestMessage'
22+
Timestamp:
23+
$ref: '#/components/messages/Timestamp'
24+
servers:
25+
echo-websocket:
26+
host: echo-websocket.hoppscotch.io
27+
protocol: wss
28+
echo:
29+
host: echo.websocket.org
30+
protocol: wss
31+
operations:
32+
sendTestMessage:
33+
action: receive
34+
channel:
35+
$ref: '#/channels/channelOne'
36+
messages:
37+
- $ref: '#/channels/channelOne/messages/TestMessage'
38+
receiveTestMessage:
39+
action: send
40+
channel:
41+
$ref: '#/channels/channelOne'
42+
messages:
43+
- $ref: '#/channels/channelOne/messages/TestMessage'
44+
receiveTimestamp:
45+
action: send
46+
channel:
47+
$ref: '#/channels/channelOne'
48+
messages:
49+
- $ref: '#/channels/channelOne/messages/Timestamp'
50+
components:
51+
messages:
52+
TestMessage:
53+
title: Test message
54+
description: Test message sent to the echo server
55+
payload:
56+
type: object
57+
properties:
58+
text:
59+
type: string
60+
description: The text of your message
61+
subtext:
62+
type: string
63+
description: Optional second message field
64+
from:
65+
type: string
66+
description: The name of the sender
67+
required:
68+
- text
69+
Timestamp:
70+
title: Timestamp
71+
description: Timestamp message sent from echo hoppscotch server
72+
payload:
73+
schema:
74+
$ref: '#/components/schemas/Timestamp'
75+
schemas:
76+
Timestamp:
77+
type: string
78+
description: Timestamp message sent from echo hoppscotch server
79+
examples:
80+
- '22:02:27 GMT+0000 (Coordinated Universal Time)'

‎docs.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,15 @@
6464
"api-playground/openapi/advanced-features"
6565
]
6666
},
67+
{
68+
"group": "AsyncAPI",
69+
"icon": "brackets-curly",
70+
"pages": [
71+
"api-playground/asyncapi/setup",
72+
"api-playground/asyncapi/playground"
73+
]
74+
75+
},
6776
{
6877
"group": "MDX",
6978
"icon": "markdown",

0 commit comments

Comments
 (0)