Configuration d’AsyncAPI

Configurez une documentation WebSocket en temps réel à l’aide de fichiers de spécification AsyncAPI pour générer des pages de référence interactives de canaux et messages.

​

Démo

Consultez l’aire de jeu WebSocket pour un exemple de l’aire de jeu AsyncAPI.

​

Ajouter un fichier de spécification AsyncAPI

Pour créer des pages pour vos canaux WebSocket, vous devez disposer d’un document de schéma AsyncAPI valide, au format JSON ou YAML, conforme à la spécification AsyncAPI 3.0.

Utilisez AsyncAPI Studio pour valider votre schéma AsyncAPI.

/votre-projet
  |- docs.json
  |- asyncapi.json

​

Remplir automatiquement les pages WebSocket

Pour générer automatiquement des pages pour tous les canaux de votre schéma AsyncAPI, ajoutez une propriété asyncapi à n’importe quel élément de navigation. La propriété asyncapi accepte un chemin d’accès vers un document de schéma AsyncAPI dans votre dépôt de documentation, une URL vers un document AsyncAPI hébergé, ou un tableau de liens vers des documents de schéma AsyncAPI.

​

Exemples avec onglets

Local file

"navigation": {
  "tabs": [
    {
        "tab": "Référence de l’API",
        "asyncapi": "/path/to/asyncapi.json"
    }
  ]
}

Lorsque vous spécifiez plusieurs fichiers AsyncAPI, chaque fichier génère son propre ensemble de pages de canaux.

​

Exemples avec des groupes

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

Le champ directory est facultatif. S’il n’est pas indiqué, Mintlify ajoute les fichiers dans le dossier api-reference du dépôt de documentation.

​

Exemples avec des groupes imbriqués

La propriété asyncapi prend en charge les groupes imbriqués. Mintlify génère les pages de canaux et les ajoute au groupe imbriqué, aux côtés des pages existantes.

C’est utile lorsque vous souhaitez organiser les canaux WebSocket comme une sous-section d’un groupe d’API plus large, ou lorsque vous devez combiner plusieurs spécifications AsyncAPI sous un groupe parent commun.

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

​

Page de canal

Si vous souhaitez mieux contrôler l’ordre de vos canaux ou ne référencer que certains canaux, créez un fichier MDX avec la propriété asyncapi dans le frontmatter.

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