Configuración de AsyncAPI

Configura documentación de WebSocket en tiempo real usando archivos de especificación AsyncAPI para generar páginas de referencia interactivas de canales y mensajes.

​

Demostración

Consulta el playground de WebSocket para ver un ejemplo del playground de AsyncAPI.

​

Agrega un archivo de especificación de AsyncAPI

Para crear páginas para tus canales WebSocket, debes contar con un documento de esquema de AsyncAPI válido en formato JSON o YAML que cumpla con la especificación de AsyncAPI 3.0.

Usa AsyncAPI Studio para validar tu esquema de AsyncAPI.

/tu-proyecto
  |- docs.json
  |- asyncapi.json

​

Generar automáticamente páginas de WebSocket

Para generar automáticamente páginas para todos los canales de tu esquema AsyncAPI, agrega una propiedad asyncapi a cualquier elemento de navegación. La propiedad asyncapi acepta una ruta a un documento de esquema AsyncAPI en tu repositorio de documentación, una URL a un documento AsyncAPI alojado o una lista de enlaces a documentos de esquemas AsyncAPI.

​

Ejemplos con pestañas

Local file

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "asyncapi": "/path/to/asyncapi.json"
    }
  ]
}

Cuando especificas varios archivos AsyncAPI, cada archivo genera su propio conjunto de páginas de canales.

​

Ejemplos con grupos

"navigation": {
  "tabs": [
    {
      "tab": "AsyncAPI",
      "groups": [
        {
          "group": "Websockets",
          "asyncapi": {
            "source": "/path/to/asyncapi.json",
            "directory": "websockets"
          }
        }
      ]
    }
  ]
}

El campo directory es opcional. Si no se especifica, Mintlify añade los archivos a la carpeta api-reference del repositorio de documentación.

​

Ejemplos con grupos anidados

La propiedad asyncapi admite grupos anidados. Mintlify genera las páginas de canal y las añade al grupo anidado, junto con cualquier página existente.

Esto resulta útil cuando quieres organizar los canales WebSocket como una subsección de un grupo de API más amplio, o cuando necesitas combinar varias especificaciones de AsyncAPI bajo un grupo principal común.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Voice API",
          "pages": [
            "voice/overview",
            {
              "group": "Voice API Commands",
              "asyncapi": "/path/to/voice-asyncapi.json"
            }
          ]
        }
      ]
    }
  ]
}

​

Página de canal

Si quieres tener más control sobre el orden de tus canales o necesitas referirte solo a canales específicos, crea un archivo MDX con la propiedad asyncapi en el frontmatter.

---
title: "Canal WebSocket"
asyncapi: "/path/to/asyncapi.json channelName"
---