Fehlerbehebung

Häufige Probleme bei API-Referenzen

Wenn Ihre API-Seiten nicht korrekt angezeigt werden, prüfen Sie diese häufigen Konfigurationsfehler:

All of my OpenAPI pages are completely blank

In diesem Szenario kann Mintlify entweder Ihr OpenAPI-Dokument nicht finden oder es ist ungültig.

Das lokale Ausführen von mint dev sollte einige dieser Probleme aufdecken.

So überprüfen Sie, ob Ihr OpenAPI-Dokument die Validierung besteht:

1. Besuchen Sie diesen Validator
2. Wechseln Sie zum Tab „Validate text“
3. Fügen Sie Ihr OpenAPI-Dokument ein
4. Klicken Sie auf „Validate it!“

Wenn das unten erscheinende Textfeld einen grünen Rand hat, hat Ihr Dokument die Validierung bestanden. Dies ist genau das Validierungspaket, das Mintlify zur Validierung von OpenAPI-Dokumenten verwendet. Wenn Ihr Dokument die Validierung hier besteht, ist die Wahrscheinlichkeit groß, dass das Problem anderswo liegt.

Außerdem unterstützt Mintlify kein OpenAPI 2.0. Wenn Ihr Dokument diese Version der Spezifikation verwendet, kann dieses Problem auftreten. Sie können Ihr Dokument unter editor.swagger.io konvertieren (unter Edit > Convert to OpenAPI 3):

One of my OpenAPI pages is completely blank

Dies wird meist durch ein falsch angegebenes openapi-Feld in den Seitenmetadaten verursacht. Achten Sie darauf, dass HTTP-Methode und Pfad exakt der HTTP-Methode und dem Pfad im OpenAPI-Dokument entsprechen.

So kann es zum Beispiel schiefgehen:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

Beachten Sie, dass der Pfad im openapi-Feld einen abschließenden Slash hat, während der Pfad im OpenAPI-Dokument keinen hat.

Ein weiterer häufiger Fehler ist ein falsch geschriebener Dateiname. Wenn Sie in openapi ein bestimmtes OpenAPI-Dokument angeben, stellen Sie sicher, dass der Dateiname korrekt ist. Wenn Sie zum Beispiel zwei OpenAPI-Dokumente openapi/v1.json und openapi/v2.json haben, könnten Ihre Metadaten so aussehen:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Requests from the API Playground don't work

Wenn Sie eine eigene Domain konfiguriert haben, könnte das an Ihrem Reverse-Proxy liegen. Standardmäßig beginnen über die API-Spielwiese gesendete Anfragen mit einer POST-Anfrage an den Pfad /_mintlify/api/request auf der Dokusite. Wenn Ihr Reverse-Proxy so konfiguriert ist, dass er nur GET-Anfragen zulässt, schlagen diese Anfragen alle fehl. Um das zu beheben, konfigurieren Sie Ihren Reverse-Proxy so, dass er POST-Anfragen an den Pfad /_mintlify/api/request zulässt.

Alternativ können Sie, wenn Ihr Reverse-Proxy POST-Anfragen grundsätzlich blockiert, Mintlify so konfigurieren, dass Anfragen mithilfe der Einstellung api.playground.proxy in der docs.json direkt an Ihr Backend gesendet werden, wie in der Einstellungsdokumentation beschrieben. Bei dieser Konfiguration müssen Sie CORS auf Ihrem Server einrichten, da Anfragen direkt aus den Browsern der Benutzer und nicht über Ihren Proxy kommen.

OpenAPI navigation entries are not generating pages

Wenn Sie eine OpenAPI-Navigationskonfiguration verwenden, die Seiten aber nicht generiert werden, prüfen Sie diese häufigen Ursachen:

1. Fehlende Standard-OpenAPI-Spezifikation: Stellen Sie sicher, dass für das Navigationselement ein openapi-Feld gesetzt ist:

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}

2. Vererbung der OpenAPI-Spezifikation: Bei verschachtelter Navigation stellen Sie sicher, dass untergeordnete Gruppen die richtige OpenAPI-Spezifikation erben oder ihre eigene angeben.

3. Validierungsprobleme: Verwenden Sie mint openapi-check <path-to-openapi-file>, um zu prüfen, ob Ihr OpenAPI-Dokument gültig ist.

Some OpenAPI operations appear in navigation but others don't

1. Verborgene Operationen: Operationen, die in Ihrer OpenAPI-Spezifikation mit x-hidden: true markiert sind, erscheinen nicht in der automatisch generierten Navigation.
2. Ungültige Operationen: Operationen mit Validierungsfehlern in der OpenAPI-Spezifikation können übersprungen werden. Überprüfen Sie Ihr OpenAPI-Dokument auf Syntaxfehler.
3. Manuelle vs. automatische Einbindung: Wenn Sie Endpunkte aus einer OpenAPI-Spezifikation referenzieren, werden in der Navigation nur die ausdrücklich referenzierten Operationen angezeigt. Es werden keine anderen Seiten automatisch hinzugefügt. Dies schließt auch Operationen ein, die in untergeordneten Navigationselementen referenziert werden.

Mixed navigation (OpenAPI and MDX pages) not working correctly

Beim Kombinieren von OpenAPI-Operationen mit regulären Dokumentationsseiten in der Navigation:

1. Dateikonflikte: Sie können nicht sowohl eine MDX-Datei als auch einen Navigationseintrag für dieselbe Operation haben. Wenn Sie zum Beispiel get-users.mdx haben, fügen Sie nicht zusätzlich "GET /users" zu Ihrer Navigation hinzu. Wenn Sie eine Datei benötigen, die denselben Namen wie eine Operation trägt, verwenden Sie die x-mint-Erweiterung für den Endpunkt, damit das href auf einen anderen Ort zeigt.
2. Pfadauflösung: Navigationseinträge, die nicht mit OpenAPI-Operationen übereinstimmen, werden als Dateipfade behandelt. Stellen Sie sicher, dass Ihre MDX-Dateien an den erwarteten Pfaden vorhanden sind.
3. Groß-/Kleinschreibung: Das Matching von OpenAPI-Operationen ist case-sensitiv. Stellen Sie sicher, dass HTTP-Methoden in Navigationseinträgen großgeschrieben sind.