Documentation de référence OpenAPI

docStatic utilise docusaurus-plugin-openapi-docs pour générer de la documentation de référence API à partir d'une spécification OpenAPI. Le plugin lit un fichier de spécification et écrit un ensemble de fichiers MDX dans votre arborescence docs/ que Docusaurus construit ensuite comme des pages normales.

Configuration

Les sources API sont configurées dans config/docusaurus/index.json sous le tableau openapi.apis. Chaque entrée spécifie un nom, le chemin vers le fichier de spécification, le répertoire de sortie et des options de regroupement optionnelles :

{
  "openapi": {
    "apis": [
      {
        "name": "petstore",
        "specPath": "openapi/petstore.yaml",
        "outputDir": "docs/api/petstore",
        "groupPathsBy": "tag",
        "categoryLinkSource": "tag"
      }
    ]
  }
}

Lancez la génération avec :

npm run gen-api-docs

Pour supprimer les fichiers générés :

npm run clean-api-docs

Pages de balises

Lorsque groupPathsBy et categoryLinkSource sont tous les deux définis sur "tag", le plugin crée une page d'index de catégorie pour chaque balise OpenAPI (par ex. store.tag.mdx). Par défaut, ces fichiers contiennent un bloc passe-partout verbeux qui importe DocCardList et useCurrentSidebarCategory — tous deux redondants dans docStatic car DocCardList est déjà enregistré globalement en tant que composant MDX, et le composant résout automatiquement les éléments de la catégorie courante lorsqu'il est appelé sans props.

docStatic configure le plugin avec un modèle de balise personnalisé qui produit à la place la forme simplifiée :

<DocCardList />

Le modèle se trouve dans config/docusaurus/openapi-tag-template.md et est connecté via l'option tagTemplate dans docusaurus.config.ts.

Modification des fichiers de balises générés

Le plugin crée un fichier de balise uniquement s'il n'en existe pas déjà un — il ne remplacera jamais un fichier que vous avez modifié. Cela signifie que vous pouvez personnaliser librement le texte de description dans une page de balise et qu'il survivra aux exécutions ultérieures de gen-api-docs. Seules les balises nouvellement introduites auront un fichier écrit pour elles, et ceux-ci utiliseront le modèle personnalisé.