OpenAPI-Referenzdokumentation

docStatic verwendet docusaurus-plugin-openapi-docs, um API-Referenzdokumentation aus einer OpenAPI-Spezifikation zu generieren. Das Plugin liest eine Spezifikationsdatei und schreibt eine Reihe von MDX-Dateien in Ihren docs/-Baum, die Docusaurus dann als normale Seiten erstellt.

Konfiguration

API-Quellen werden in config/docusaurus/index.json unter dem Array openapi.apis konfiguriert. Jeder Eintrag gibt einen Namen, den Pfad zur Spezifikationsdatei, das Ausgabeverzeichnis und optionale Gruppierungsoptionen an:

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

Generierung starten mit:

npm run gen-api-docs

Generierte Dateien entfernen:

npm run clean-api-docs

Tag-Seiten

Wenn groupPathsBy und categoryLinkSource beide auf "tag" gesetzt sind, erstellt das Plugin für jeden OpenAPI-Tag eine Kategorie-Indexseite (z. B. store.tag.mdx). Standardmäßig enthalten diese Dateien einen ausführlichen Boilerplate-Block, der DocCardList und useCurrentSidebarCategory importiert – beide redundant in docStatic, da DocCardList bereits global als MDX-Komponente registriert ist und die Komponente die Elemente der aktuellen Kategorie automatisch auflöst, wenn sie ohne Props aufgerufen wird.

docStatic konfiguriert das Plugin mit einer benutzerdefinierten Tag-Vorlage, die stattdessen die vereinfachte Form erzeugt:

<DocCardList />

Die Vorlage befindet sich in config/docusaurus/openapi-tag-template.md und wird über die Option tagTemplate in docusaurus.config.ts eingebunden.

Bearbeitung generierter Tag-Dateien

Das Plugin erstellt eine Tag-Datei nur, wenn noch keine vorhanden ist – es wird niemals eine von Ihnen bearbeitete Datei überschreiben. Das bedeutet, dass Sie den Beschreibungstext in einer Tag-Seite frei anpassen können und er nachfolgende gen-api-docs-Läufe übersteht. Nur neu eingeführte Tags erhalten eine Datei, und diese verwenden die benutzerdefinierte Vorlage.