Asyncapi Docs

api-playground/asyncapi/playground.mdx

@@ -0,0 +1,5 @@
+---
+title: "Playground"
+description: "Enable users to interact with your websockets"
+asyncapi: "/asyncapi.yaml channelOne"
+---

api-playground/asyncapi/setup.mdx

@@ -0,0 +1,83 @@
+---
+title: "AsyncAPI Setup"
+description: "Create websocket reference pages with AsyncAPI"
+---
+
+## Add an AsyncAPI specification file
+
+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+.
+
+<Tip>
+  To make sure your AsyncAPI schema is valid, you can paste it into the
+  [AsyncAPI Studio](https://studio.asyncapi.com/)
+</Tip>
+
+## Auto-populate websockets pages
+
+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.
+
+**Examples with Tabs:**
+
+<CodeGroup>
+
+```json Local File {5}
+"navigation": {
+  "tabs": [
+    {
+        "tab": "API Reference",
+        "asyncapi": "/path/to/asyncapi.json"
+    }
+  ]
+}
+
+```
+
+```json Remote URL {5}
+"navigation": {
+  "tabs": [
+    {
+        "tab": "API Reference",
+        "asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
+    }
+  ]
+}
+```
+
+</CodeGroup>
+
+**Examples with Groups:**
+
+```json {8-11}
+"navigation": {
+  "tabs": [
+    {
+      "tab": "AsyncAPI",
+      "groups": [
+        {
+          "group": "Websockets",
+          "asyncapi": {
+            "source": "/path/to/asyncapi.json",
+            "directory": "api-reference"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+<Note>
+  The directory field is optional. If not specified, the files will be placed in
+  the **api-reference** folder of the docs repo.
+</Note>
+
+## Channel Page
+
+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.
+
+```mdx
+---
+title: "Websocket Channel"
+asyncapi: "/path/to/asyncapi.json channelName"
+---
+```

asyncapi.yaml

@@ -0,0 +1,80 @@
+asyncapi: 3.0.0
+info:
+  title: Test websocket schema
+  version: 1.0.0
+  description: This is a test websocket API.
+channels:
+  channelOne:
+    title: Test channel
+    description: >-
+      This is a websocket channel.
+
+      It can have _markdown_ in the description.
+
+      * Use the "echo-websocket.hoppscotch.io" server to receive timestamped messages every second.
+
+      * Use the "echo.websocket.org" server to send test messages to the websocket. This server will echo back any messages you send to it.
+
+    address: /
+    messages:
+      TestMessage:
+        $ref: '#/components/messages/TestMessage'
+      Timestamp:
+        $ref: '#/components/messages/Timestamp'
+servers:
+  echo-websocket:
+    host: echo-websocket.hoppscotch.io
+    protocol: wss
+  echo:
+    host: echo.websocket.org
+    protocol: wss
+operations:
+  sendTestMessage:
+    action: receive
+    channel:
+      $ref: '#/channels/channelOne'
+    messages:
+      - $ref: '#/channels/channelOne/messages/TestMessage'
+  receiveTestMessage:
+    action: send
+    channel:
+      $ref: '#/channels/channelOne'
+    messages:
+      - $ref: '#/channels/channelOne/messages/TestMessage'
+  receiveTimestamp:
+    action: send
+    channel:
+      $ref: '#/channels/channelOne'
+    messages:
+      - $ref: '#/channels/channelOne/messages/Timestamp'
+components:
+  messages:
+    TestMessage:
+      title: Test message
+      description: Test message sent to the echo server
+      payload:
+        type: object
+        properties:
+          text:
+            type: string
+            description: The text of your message
+          subtext:
+            type: string
+            description: Optional second message field
+          from:
+            type: string
+            description: The name of the sender
+        required:
+          - text
+    Timestamp:
+      title: Timestamp
+      description: Timestamp message sent from echo hoppscotch server
+      payload:
+        schema:
+          $ref: '#/components/schemas/Timestamp'
+  schemas:
+    Timestamp:
+      type: string
+      description: Timestamp message sent from echo hoppscotch server
+      examples:
+        - '22:02:27 GMT+0000 (Coordinated Universal Time)'

docs.json

@@ -64,6 +64,15 @@
                   "api-playground/openapi/advanced-features"
                 ]
               },
+              {
+                "group": "AsyncAPI",
+                "icon": "brackets-curly",
+                "pages": [
+                  "api-playground/asyncapi/setup",
+                  "api-playground/asyncapi/playground"
+                ]
+
+              },
               {
                 "group": "MDX",
                 "icon": "markdown",