Das Coze-Plugin kann OpenAPI 3.1 nicht importieren, und dieses Problem ist nicht ungewöhnlich, besonders wenn man einfach die fertigen Interface-Definitionen einfügt. Viele Leute denken, sie ändern nur ein oder zwei Felder, aber tatsächlich ist Cozes Plugin-Parsing empfindlicher gegenüber der Schemastruktur, und der wahrscheinlichste Ort, an dem man stecken bleibt, ist der Antwort-Body-Typ.
Die häufige Fehlermeldung in der Community ist sehr konsistent: nicht "die Schnittstelle ist nicht nutzbar", sondern "die Schnittstellendokumentation ist nicht so, wie Coze es erwartet". Zum Beispiel werden einige 3.1-Schreibmethoden, leere Antwortschemata und übermäßig komplexe Joint-Typen direkt während des Importprozesses blockiert.
Warum OpenAPI 3.1 anfälliger für Probleme ist
Da 3.1 ausdrucksstärker ist, behandelt der Plugin-Importeur möglicherweise nicht alle fortgeschrittenen Schriften als nutzbare Eingabe. Für Nutzer bezieht sich die Dokumentation auf die Spezifikationen; Für Importeure erkennt es möglicherweise nur einige der einfachsten Strukturen. Im öffentlichen Issue blieb jemand an einer Stelle wie "Response Body unterstützt nur Objekttypen" hängen, was darauf hindeutet, dass Plugin-Importe in ihren Anforderungen an die Rückgabestruktur nicht locker sind.
Wenn du weniger in die Grube treten willst, mach zuerst diese drei Dinge
- Konvergiere OpenAPI zuerst auf einen einfacheren 3.0.x-Stil.
- Halte den Befragten so standardmäßig wie möglich "Objekt" und schreibe keine komplexen, verschachtelten oder leeren Schemata einfach aus.
- Vereinfache die erforderlichen Felder, Request Body und bring Body zur minimal nutzbaren Version zurück und füge sie dann schrittweise hinzu.
Eine praktischere Art, damit in der Gemeinschaft umzugehen,
Viele Leute "reparieren Coze" nicht, sondern ordnen ihre OpenAPI-Dateien zurück und ändern sie konservativer. Der Grund dafür ist realistisch: Das Ziel von Coze-Plugin-Importen ist es nicht, die gesamte OpenAPI-Syntax zu verschlingen, sondern Schnittstellen stabil in aufrufbare Plugins umzuwandeln. Je länger das Dokument eingewickelt wird, desto wahrscheinlicher ist es, dass der Import fehlschlägt.
Wenn Sie beim Import hängen bleiben, wird empfohlen zu prüfen, ob der Fehler auf die Struktur, den Typ oder den Feldnamen hinweist, anstatt zunächst zu vermuten, dass die Schnittstelle selbst unbrauchbar ist. Oft ist das Schema einfach zu ausgefallen und der Importeur will nicht raten.
Ein-Satz-Schluss
Das Scheitern des Coze-Plugins, OpenAPI 3.1 zu importieren, liegt größtenteils nicht daran, dass die Schnittstelle falsch geschrieben wurde, sondern vielmehr daran, dass die Dokumentstruktur zu komplex ist und der Rückgabe-Body nicht dem Standard entspricht. Vereinfacht man das Schema zunächst, ist die Erfolgsquote in der Regel deutlich höher.
