Fehlerbehebung von API-Importproblemen

Dieser Artikel ist eine konsolidierte Referenz für jeden Fehler, jede Warnung und jedes unerwarteten Verhaltens, das in der API-Dokumentationsfunktion von Document360 dokumentiert ist. Nutzen Sie es, um Probleme mit Importen, Authentifizierung, der Try It!-Funktion, dem Rendering und der Knowledge Base-Seite zu diagnostizieren und zu beheben.

Importfehler

Ungültiges Format – API-Dateihochladen fehlgeschlagen

Wenn es eintritt: Wenn eine oder mehrere Antworten in Ihrer OpenAPI-Spezifikationsdatei den erforderlichen content Abschnitt fehlen.

Warum es passiert: Document360 setzt strenge OpenAPI-Validierungsregeln durch. Obwohl eine Datei die Validierung in Tools wie Swagger Editor bestehen kann, verlangt Document360, dass alle Antworten sowohl den Medientyp (zum Beispiel application/json) als auch eine Schemareferenz unter einem content Block explizit definieren. Antworten, die leer sind oder ein Schema direkt ohne Wrapper content referenzieren, verursachen diesen Fehler.

Wie man es behebt:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei in einem Texteditor oder IDE.
2. Finden Sie alle Antwortdefinitionen, die leer sind oder ein Schema ohne Block content referenzieren.
   Falsch:

   responses:
     "200": {}

Korrekt:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Speichere die Datei und lade sie erneut in Document360 hoch.
   Wenn das Problem weiterhin besteht, wenden Sie sich an das Document360-Supportteam .

Ungültige URL

Wenn es eintritt: Beim Erstellen einer API-Referenz aus einer URL kann die angegebene URL nicht abgerufen oder aufgelöst werden.

Warum es passiert: Die URL kann fehlerhaft sein, von den Servern von Document360 aus nicht erreichbar sein oder auf eine Ressource verweisen, die keine gültige OpenAPI-Spezifikation ist.

Wie man es behebt: Überprüfen Sie, ob die URL korrekt im Browser oder mit curlaufgelöst wird. Stellen Sie sicher, dass ein gültiges JSON- oder YAML-OpenAPI-Dokument zurückgegeben wird. Korrigiere die URL und versuche es erneut.

Nicht unterstütztes Dateiformat

Wenn es eintritt: Wenn die hochgeladene Datei kein unterstütztes Format ist.

Wie man es behebt: Stellen Sie sicher, dass Ihre Datei eine der folgenden Dateien ist: JSON, YAML oder YML. Document360 unterstützt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 und Postman Collections.

API-Referenz kann nicht hinzugefügt werden – ungültige Spezifikationsdatei

Fehlermeldung: "API-Referenz kann nicht hinzugefügt werden. Diese Operation kann nicht durchgeführt werden. Bitte stellen Sie sicher, dass Sie eine gültige Spezifikationsdatei vorgelegt haben."

Wenn es eintritt: Beim Hochladen einer YAML-Spezifikationsdatei, die aus einem Rich-Text-Editor oder Textverarbeitungsprogramm kopiert oder exportiert wurde.

Warum es passiert: Die hochgeladene YAML-Datei ist fehlgebildet und kein gültiges OpenAPI 3.0 YAML-Dokument. Dies geschieht häufig, wenn die Datei aus einem Rich-Text-Editor kopiert oder exportiert wurde, der formatierende Zeichen wie \f0\fs24 oder nachlaufende Backslashes einführt, die das YAML-Format durchbrechen.

1. Validiere deine Spezifikationsdatei: Öffne deine YAML-Datei in einem Tool wie Swagger Editor oder einem Code-Editor, um Fehler oder Formatierungsfehler zu überprüfen.
2. Achten Sie auf unerwünschte Formatierungszeichen: Überprüfen Sie Zeichen wie \f0\fs24 oder nachlaufende Backslashes \ (insbesondere in der Endpunktbeschreibung), die beim Copy-Paste aus einer Rich-Text-Quelle eingeführt wurden. Diese können das YAML-Format zerstören.
3. Bereinigen Sie die Datei: Verwenden Sie einen einfachen Text- oder Code-Editor, um spezielle Formatierungszeichen zu entfernen. Vermeide es, Textverarbeitungsprogramme beim Bearbeiten oder Speichern von YAML-Dateien zu verwenden.
4. Die Datei erneut hochladen: Nachdem Sie die Datei bereinigt und sichergestellt haben, dass es ein gültiges OpenAPI 3.0 YAML ist, versuchen Sie, sie erneut hochzuladen.

Zusammenfassung und Tags werden nach dem Import nicht angezeigt

Wenn es eintritt: Nach dem Import einer Spezifikation zeigen Endpunkt-Artikel falsche Titel an oder erscheinen unter unerwarteten Kategorieordnern.

Warum es passiert: Die summary und-Felder tags sind auf Pfadebene im Spec definiert und nicht innerhalb des Operationsobjekts (get, post, put, oder delete). Zusätzlich muss das Feld tags immer als Array geschrieben werden, selbst wenn nur ein Tag verwendet wird.

Wie man es behebt:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei in einem Texteditor.
2. Verschieben Sie die summary und-Felder tags innerhalb jedes Operationsobjekts und stellen Sie sicher, dass tags dies als Array geschrieben wird.
   Falsch:

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

Korrekt:

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Speichere die Datei und importiere sie erneut in Document360. Die importierten Artikel verwenden den summary Wert als Artikeltitel, und tagbasierte Ordner werden korrekt erstellt.
   Wenn das Problem weiterhin besteht, wenden Sie sich an das Document360-Supportteam .

Upload schlägt mit 400 Bad Request fehl – Spezifikationsdatei ist zu groß

Wenn es eintritt: Beim Hochladen einer gültigen YAML- oder JSON-OpenAPI-Spezifikationsdatei, die Endpunkte mit tief verschachtelten Antwortschemata und mehreren Antwortcodes pro Endpunkt enthält.

Warum es passiert: Obwohl die Datei gültig YAML sein und externe Validatoren wie Swagger Editor bestehen kann, setzt Document360 eine interne Artikelgrößenbegrenzung durch. Wenn ein Endpunkt Antwortschemata enthält, die acht oder mehr Ebenen tief über mehrere Antwortcodes verschachtelt sind, überschreitet die resultierende Datengröße diese Grenze und kann nicht verarbeitet oder gespeichert werden.

Wie man es behebt:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei in einem Texteditor oder IDE.
2. Für jeden Endpunkt behalte man nur einen 201-Antworttyp, einen 400-Serien-Antworttyp und den Standard-Antworttyp. Entfernen Sie alle zusätzlichen Antwortcodes.
3. Für Endpunkte, bei denen allein die 201-Antwort tief verschachtelte Schemata enthält, behalten Sie nur den 201-Antworttyp und entfernen Sie die 400er-Serien- und Standardantworttypen vollständig.
4. Speichere die geänderte Datei und lade sie erneut in Document360 hoch.

i️ HINWEIS
Wenn die Veröffentlichung nach einem erfolgreichen Upload fehlschlägt, kontaktieren Sie das Support-Team von Document360. Das Publizieren kann aufgrund der Begrenzung der Artikelgröße Unterstützung im Backend erfordern.

Top-level-Tag-Beschreibungen, die in der API-Dokumentation nicht dargestellt werden

Wenn es eintritt: Beschreibungen und Metadaten, die in obersten OpenAPI-Tag-Objekten definiert sind, werden in der generierten API-Dokumentation nicht angezeigt.

Warum es passiert: Wenn eine OpenAPI-Spezifikationsdatei Top-Level-Tags enthält, die zur Gruppierung von API-Operationen verwendet werden, wandelt Document360 diese Tags während des Imports in Ordnertyp-Kategorien um. Ordnerkategorien werden nur zur Organisation von Endpunkten verwendet und generieren keine eigenständigen Inhaltsseiten. Daher werden keine Beschreibung oder Metadaten, die in diesen Top-Level-Tag-Objekten definiert sind, gerendert.

Workaround: Füge den relevanten Kontext direkt zu den einzelnen Endpunktbeschreibungen innerhalb des Tags hinzu, sodass die Informationen auf den generierten Endpunktseiten sichtbar sind.

Hast du immer noch Probleme?

Wenn die oben genannten Schritte Ihr Problem nicht lösen, wenden Sie sich direkt an das Support-Team von Document360 .

FAQ