Wenn Sie derzeit einzelne MDX-Seiten für Ihre API-Endpunkte verwenden, können Sie auf das automatische Generieren von Seiten aus Ihrer OpenAPI-Spezifikation umsteigen und dabei die Anpassbarkeit einzelner Seiten beibehalten. Das hilft Ihnen, die Anzahl der zu pflegenden Dateien zu reduzieren und die Konsistenz Ihrer API-Dokumentation zu verbessern. Sie können Metadaten und Inhalte für jeden Endpunkt in Ihrer OpenAPI-Spezifikation definieren und die Endpunkte in der Navigation nach Bedarf anordnen.

​
CLI-Migration

Der Befehl mint migrate-mdx ist die empfohlene Methode, um von MDX-Endpunktseiten auf automatisch generierte Seiten zu migrieren. Dieser Befehl:
  • Analysiert die Navigationsstruktur deiner docs.json.
  • Identifiziert MDX-Seiten, die OpenAPI-Endpunktseiten erzeugen.
  • Extrahiert Inhalte aus MDX-Dateien und verschiebt sie in die x-mint-Erweiterung deiner OpenAPI-Spezifikation.
  • Aktualisiert deine docs.json, um direkt auf die OpenAPI-Endpunkte statt auf MDX-Dateien zu verweisen.
  • Löscht die ursprünglichen MDX-Endpunktdateien.
Wenn du bereits x-mint für einen Endpunkt definiert hast und zusätzlich eine MDX-Seite mit Inhalt für diesen Endpunkt existiert, überschreibt der MDX-Inhalt die bestehenden x-mint-Einstellungen.Wenn du mehrere MDX-Seiten für denselben Endpunkt mit unterschiedlichem Inhalt hast, verwendet das Skript den Inhalt der Seite, die in deiner docs.json zuletzt aufgeführt ist.Das Migrationstool unterstützt keine Vorschau der Änderungen, bevor sie angewendet werden.
1

Bereite deine OpenAPI-Spezifikation vor.

Stelle sicher, dass deine OpenAPI-Spezifikation gültig ist und alle Endpunkte enthält, die du dokumentieren möchtest.Alle MDX-Seiten, die du migrieren möchtest, müssen das openapi:-Frontmatter mit Verweis auf einen Endpunkt enthalten.
Validiere deine OpenAPI-Datei mit dem Swagger Editor oder der Mint CLI.
2

Installiere die Mint CLI

Falls nötig, installiere oder aktualisiere die Mint CLI.
3

Führe den Migrationsbefehl aus.

mint migrate-mdx

​
Manuelle Migrationsschritte

1

Bereiten Sie Ihre OpenAPI-Spezifikation vor.

Stellen Sie sicher, dass Ihre OpenAPI-Spezifikation gültig ist und alle Endpunkte enthält, die Sie dokumentieren möchten.Für Endpunkte, deren Metadaten oder Inhalte Sie anpassen möchten, fügen Sie dem Endpunkt die Erweiterung x-mint hinzu. Weitere Details finden Sie unter x-mint extension.Für Endpunkte, die Sie aus Ihrer Dokumentation ausschließen möchten, fügen Sie dem Endpunkt die Erweiterung x-hidden hinzu.
Validieren Sie Ihre OpenAPI-Datei mit dem Swagger Editor oder der Mint CLI.
2

Aktualisieren Sie Ihre Navigationsstruktur.

Ersetzen Sie MDX-Seitenverweise in Ihrer docs.json durch OpenAPI-Endpunkte.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Entfernen Sie alte MDX-Dateien.

Nachdem Sie überprüft haben, dass Ihre neue Navigation korrekt funktioniert, entfernen Sie die MDX-Dateien für Endpunkte, die Sie nicht mehr benötigen.
Sie können anpassen, wie Ihre API-Dokumentation in der Navigation angezeigt wird.
Kombinieren Sie automatisch generierte API-Seiten mit anderen Seiten: 
"navigation": {
  "groups": [
    {
      "group": "API-Referenz",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
Mehrere API-Versionen

Organisieren Sie verschiedene API-Versionen mit Tabs oder Gruppen: 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2",
      "openapi": "specs/v2.json"
    }
  ]
}

​
Wann Sie einzelne MDX-Seiten verwenden sollten

Behalten Sie einzelne MDX-Seiten bei, wenn Sie Folgendes benötigen:
  • Umfassende individuelle Inhalte pro Endpoint, z. B. React-Komponenten oder ausführliche Beispiele.
  • Einzigartige Seitenlayouts.
  • Experimentelle Dokumentationsansätze für bestimmte Endpoints.
Für die meisten Anwendungsfälle bietet die OpenAPI-Navigation eine bessere Wartbarkeit und Konsistenz.