Diese Seite ist der kanonische Leitfaden zum Prüfen von OpenAPI- und Swagger-Dokumenten im Browser mit DevUtilities. Fügen Sie oben eine Spec ein, während Sie lesen, oder springen Sie zu einem Thema unten. Die Validierung bleibt lokal — Dokumente werden nie hochgeladen. Wenn der Lint grün ist, leiten Sie an Kiota SDK Engine weiter für Bereitschaftsbewertung und generate-Befehlsvorschau.

OpenAPI Validator ist ein clientseitiger Linter für OpenAPI 3 und Swagger 2 als JSON/YAML. Er meldet VALID, VALID WITH WARNINGS oder INVALID mit pfadbezogenen Diagnosen, damit Sie Blocker vor SDK-Generierung oder Gateway-Import beheben.

Was Sie erhalten

• Prüft OpenAPI-3.x- und Swagger-2-Dokumente (JSON oder YAML)
• Statusbanner: VALID / VALID WITH WARNINGS / INVALID
• Prüft Versionskeys, Pfadabdeckung, servers und häufige Strukturprobleme
• Nur lokaler Lint — sicher für interne API-Specs
• Direkter Übergabepfad zu Kiota SDK Engine für Codegen-Bereitschaft

Verwenden Sie dieses Tool, wenn

• Sie brauchen einen schnellen Vorabcheck vor Microsoft Kiota oder anderen Generatoren
• CI oder eine PR-Checkliste verlangt einen lesbaren Lint der committed Spec
• Sie haben eine Swagger-2-Datei geerbt und wollen Migrationswarnungen vor OpenAPI-3-Arbeit
• Doppelte operationId oder kaputte $ref lassen den Codegen weiter scheitern

Bevorzugen Sie ein verwandtes Tool, wenn

• Sie brauchen vollständige Kiota-Bereitschaft, Sprachmatrix und CLI-Builder → Kiota SDK Engine
• Sie wollen nur JSON-Payloads verschönern → JSON Formatter
• Sie brauchen Mock-Response-Arrays → JSON Generator

Codegeneratoren (besonders Kiota) scheitern laut an Strukturproblemen, die ein flüchtiger YAML-Blick übersieht. Prüfen Sie hier zuerst, dann öffnen Sie Kiota SDK Engine für generatorspezifische Bereitschaft.

Blocker vor dem Codegen beseitigen

• Doppelte oder fehlende operationId (Methodennamen-Kollisionen)
• Fehlende oder leere responses bei Erfolgsstatuscodes
• Ungültige oder hängende $ref in components
• Fehlender openapi/swagger-Versionskey oder leeres paths-Objekt
• Zirkuläre Schema-Referenzen (tauchen oft als Nächstes in Kiota auf)

Warnungen, die Sie aufschieben können

• Fehlendes servers[] — Clients brauchen möglicherweise --base-url-Overrides
• Swagger-2-Migrationshinweise — bevorzugen Sie OpenAPI 3 für neue APIs
• Spärliche Beschreibungen — Dokumentationsqualität, keine Parse-Blocker

Erste Schritte vor der SDK-Generierung.

1. Fügen Sie OpenAPI 3 oder Swagger 2 als JSON oder YAML in das Eingabefeld ein.
2. Lesen Sie den Status: VALID, VALID WITH WARNINGS oder INVALID.
3. Beheben Sie jeden Fehler in der Diagnoseliste — beginnen Sie mit operationId, responses und $ref-Fehlern.
4. Prüfen Sie erneut, bis der Status VALID ist oder nur akzeptable Warnungen bleiben.
5. Leiten Sie die bereinigte Spec an Kiota SDK Engine weiter für Score, Sprachvorschau und kiota-generate-Befehl.
6. Committen Sie das korrigierte Dokument und fügen Sie diesen Lint optional als PR-Checklistenpunkt hinzu.

Pull Requests mergen OpenAPI-Änderungen, die später die nächtliche SDK-Regeneration brechen. Reviewer können doppelte operationIds nicht mit bloßem Auge erkennen.

So löst dieses Tool das Problem

1. Fügen Sie das OpenAPI-Dokument des PRs während des Reviews in den Validator ein.
2. Verlangen Sie VALID (oder nur dokumentierte Warnungen) vor dem Approve.
3. Nennen Sie doppelte operationId und kaputte $ref im Review-Thread mit dem Diagnosetext.
4. Führen Sie nach dem Merge Kiota in CI gegen dasselbe Dokument aus.

Ein Lint-Gate in menschlicher Geschwindigkeit, das dieselbe Fehlerklasse wie Generatoren trifft — ohne die Spec hochzuladen.

Ein Team steht kurz vor kiota generate und will Sicherheit, dass das Dokument nicht an Namens- oder $ref-Problemen scheitert.

So löst dieses Tool das Problem

1. Prüfen Sie das Dokument hier, bis INVALID beseitigt ist.
2. Leiten Sie an Kiota SDK Engine weiter und prüfen Sie den OpenAPI-Readiness-Score.
3. Beheben Sie verbleibende Kiota-spezifische Probleme (Zirkelrefs, Nullable-Stil) in den Kiota-Diagnosen.
4. Kopieren Sie den generierten CLI-Befehl, sobald die Bereitschaft akzeptabel ist.

Ein zweistufiger lokaler Workflow: struktureller Lint → Kiota-Bereitschaft → generate auf Ihrem Rechner.

Ein älteres Swagger-2-JSON betreibt noch ein Gateway. Stakeholder wollen OpenAPI 3 vor der Kiota-Adoption.

So löst dieses Tool das Problem

1. Fügen Sie das Swagger-2-Dokument ein und notieren Sie Migrationswarnungen.
2. Beheben Sie strukturelle INVALID-Probleme, die jeden Konverter blockieren würden.
3. Planen Sie eine OpenAPI-3-Migration für neue Features; behalten Sie Swagger 2 nur solange es gated ist.
4. Prüfen Sie das OpenAPI-3-Ergebnis erneut vor Kiota.

Klares Signal, dass Swagger 2 mit Warnungen geparst wird — bevorzugen Sie OpenAPI 3 für neue SDK-Arbeit.

Generatoren benennen Client-Methoden nach operationId. Duplikate verursachen Kollisionen.

Warum das passiert

Zwei oder mehr Operationen teilen dieselbe operationId, oder operationId fehlt, wo der Generator sie verlangt.

Diagnose

Suchen Sie im Dokument nach wiederholten operationId-Werten. Kiota und dieser Linter markieren Kollisionen — beheben Sie sie hier, bevor Sie die SDK-Engine öffnen.

Behebungen

1. Weisen Sie jeder Operation eine eindeutige operationId zu (Verb + Ressource ist ein gängiges Muster).
2. Entfernen Sie ungenutzte doppelte Paths, die beim Bearbeiten kopiert wurden.
3. Beim Zuschneiden für ein Teil-SDK widersprechende Paths entfernen statt Produktions-IDs leichtfertig umzubenennen.

Nach dem Umbenennen erneut prüfen und dann die Kiota-Bereitschaft neu bewerten — Methodennamen in Vorschauen ändern sich.

Operationen ohne nutzbare responses brechen die typisierte Client-Generierung.

Warum das passiert

Eine Path-Operation lässt responses weg, oder Erfolgs-responses haben leeres content {} ohne Schema.

Diagnose

Prüfen Sie die responses-Map jeder Operation auf 200/201- (oder default-)Einträge und stellen Sie sicher, dass Content-Schemas auflösen.

Behebungen

1. Fügen Sie mindestens eine Erfolgs-response mit application/json (oder relevantem) Media-Type hinzu.
2. Verweisen Sie das Content-Schema per $ref auf components.schemas statt content leer zu lassen.
3. Dokumentieren Sie Fehler-responses (4xx/5xx), wenn Clients sie behandeln müssen — Warnungen können bei Auslassung bleiben.

Ungültige $ref-Zeiger verhindern Schema-Auflösung während Lint und Codegen.

Warum das passiert

Ein $ref zeigt auf eine fehlende Komponente, nutzt einen falschen JSON Pointer oder bildet einen Zyklus, den der Resolver nicht expandieren kann.

Diagnose

Folgen Sie jedem fehlgeschlagenen $ref-Pfad in components.schemas / parameters / responses. Bestätigen Sie, dass der Zielschlüssel existiert und die Schreibweise passt.

Behebungen

1. Reparieren oder erstellen Sie das fehlende Komponenten-Ziel neu.
2. Normalisieren Sie $ref-Strings auf #/components/...-Zeiger.
3. Brechen Sie Zirkelreferenzen, indem Sie flache DTOs extrahieren (als Nächstes gilt Kiotas Zirkelref-Leitfaden).

Interpretieren Sie das Banner, bevor Sie das Dokument ändern.

OpenAPI Validator und Kiota SDK Engine ergänzen sich. Prüfen Sie hier die strukturelle Gesundheit; nutzen Sie Kiota für Generator-Bereitschaft, Sprachmatrix, Endpoint-Auswahl und CLI-Befehlsexport.

• Leiten Sie die bereinigte Spec nach VALID an Kiota SDK Engine weiter oder fügen Sie sie dort ein.
• Nutzen Sie Kiota-Diagnosen für doppelte operationId, zirkuläre $ref und Nullable-Stil-Probleme, die Generatoren betonen.
• Kopieren Sie kiota generate aus dem Kiota-Generate-Schritt — die Dateiausgabe läuft weiterhin über die lokale Kiota-CLI.
• Halten Sie beide Tools clientseitig, damit interne API-Verträge den Browser nie verlassen.

• Prüfen Sie bei jedem OpenAPI-PR vor dem Approve.
• Bevorzugen Sie OpenAPI 3 für neue APIs; behandeln Sie Swagger 2 als Legacy mit Migrationswarnungen.
• Halten Sie operationId eindeutig und stabil — Umbenennungen churnen generierte Clients.
• Geben Sie Erfolgs-responses immer ein auflösbares Schema.
• Beseitigen Sie INVALID, bevor Sie Kiota öffnen; nutzen Sie Kiota danach für generatorspezifische Bereitschaft.
• Laden Sie interne Specs nicht zu Drittanbieter-Lint-SaaS hoch, wenn dieser lokale Pfad reicht.