OpenAPI 3 / Swagger online validieren vor der CI

Warum eine OpenAPI-Spec vor dem Merge validieren?

Eine ungültige OpenAPI-Spec blockiert Client-Generatoren, lässt API-Gateway-Imports scheitern und verzögert Contract-Reviews. Die häufigsten Fehler — unvollständiges info, defekte interne $ref, nicht unterstützte openapi-Version — verstecken sich oft in einem 500-zeiligen YAML-Diff. Der Online-OpenAPI-Validator von FastMinify prüft die Schema-Konformität für OpenAPI 3.0, 3.1 und 3.2 über @scalar/openapi-parser, vollständig im Browser. JSON oder YAML einfügen: Urteil, Fehlerpfade und Spec-Statistiken erscheinen ohne Server-Upload. Ergänzen Sie mit dem OpenAPI-Formatter für lesbare Reviews und erkunden Sie den API-Tools-Hub. Bei fragwürdiger JSON-Syntax starten Sie mit dem JSON-Validator; zur Payload-Optimierung nach validiertem Vertrag siehe unseren REST-API-Performance-Leitfaden.

OpenAPI-3.0–3.2-Schemafehler vor CI oder Gateway-Import erkennen

JSON und YAML akzeptiert — Auto-Erkennung mit YAML-Fallback bei JSON-Parse-Fehler

Interne <code>#/…</code>-Referenzen geprüft; Scalar-Issue-Pfade angezeigt

100 % lokal — Ihre Spec verlässt den Browser nicht (ideal für interne Verträge)

Schneller Workflow: validieren → formatieren → linten → commit

Ehrliche Grenzen und Best Practices

Was validate-openapi nicht tut

Ein „gültig“-Urteil bedeutet OpenAPI-Schema-Konformität — nicht, dass Ihre API in Produktion korrekt antwortet.

Kein Fetch externer oder remote $ref-URLs

Kein automatisches Multi-File-Bundle — eine Einzeldatei-Spec pro Einfügen

Keine Swagger-2.0-Validierung

Kein Security-Testing (echte Auth, effektive Scopes)

512-KiB-Eingabelimit — riesige Specs brauchen lokale Tools oder CI

Interne vs. externe Referenzen

#/-Referenzen werden von Scalar geprüft. HTTP(S)-Referenzen auf andere Dateien werden nie aufgelöst — die Spec muss für zuverlässige Browser-Validierung eigenständig sein.

Einzeldatei bevorzugen oder upstream mit CI-Tool bundeln

Ungelöste externe $ref kann Parse bestehen, anderswo scheitern

Cross-Repo-Imports nach lokaler Validierung manuell prüfen

json-schema-to-openapi und openapi-to-json-schema im Hub für Schema-Pivots

Daten gegen Schema validieren: json-schema-validator — siehe unseren JSON-Schema-Leitfaden

CI-Integration und Ergänzungen

Das Browser-Tool beschleunigt Feedback vor dem Commit; CI bleibt Source of Truth für Teams.

Geänderte Spec vor git push einfügen — schneller als volle Pipeline

In CI: Spectral, openapi-cli oder Redocly je nach Stack

Kombinieren mit unserem CI/CD-Leitfaden für breitere Automatisierung

Ziel-OpenAPI-Version (3.0 vs. 3.1) im Repo-README dokumentieren

Schema-Breaking-Changes mit json-diff auf JSON-Exports prüfen

OpenAPI 3 vs. Swagger 2: Was das Tool prüft (und ablehnt)

OpenAPI 3.x: der moderne Vertrag

OpenAPI 3.x beschreibt REST-Endpunkte, Request-/Response-Schemas, Security und wiederverwendbare Komponenten. FastMinify validiert die Konformität zum OpenAPI-Metaschema — nicht das Laufzeitverhalten Ihrer API.

Unterstützte Versionen: 3.0.x, 3.1.x, 3.2.x

Typische Pflichtfelder: openapi, info.title, info.version, paths

Komponenten schemas, responses, parameters — interne Refs aufgelöst

Strukturelle Scalar-Validierung — kein Test echter HTTP-Aufrufe

YAML oder JSON: gleiche Semantik nach dem Parse

Swagger 2.0 ausdrücklich abgelehnt

Dokumente mit Root-Key swagger: "2.0" werden von diesem Tool nicht unterstützt. Die Fehlermeldung ist eindeutig — validieren Sie sie hier nicht.

Swagger 2 nutzt swagger; OpenAPI 3 nutzt openapi

Swagger → OpenAPI-3-Migration: dedizierte Konverter upstream verwenden

FastMinify behauptet keine Swagger-2-Validierung — keine falschen Positiven

Nach Migration erneut mit validate-openapi prüfen

Hybride oder fehlerhafte Specs scheitern beim Parse vor der Validierung

Häufige Fehler in echten Specs

Jenseits der Syntax brechen diese strukturellen Lücken CI oder SDK-Generatoren.

Interne $ref auf fehlende Komponente — Validierungsfehler

HTTP-Response ohne description — OpenAPI-Regelverletzung

Doppelte oder fehlende operationId — blockiert manche Generatoren

Schema-type inkompatibel mit schlecht verschachteltem nullable / oneOf

JSON-Schema-Draft-Mix in components — 3.1 vs. 3.0 Konformitätsfehler

Validate vs. Lint vs. Format

Drei unterschiedliche Absichten im API-Hub — verwechseln Sie sie beim PR-Review nicht.

Validate: OpenAPI-Schema-Konformität (Scalar) — gültig/ungültig

Format: Einrückung und Lesbarkeit — keine semantischen Korrekturen

Lint: Spectral-ähnliche Regeln (operationId, tags…) — siehe unseren OpenAPI-Lint- und Format-Leitfaden

Empfohlene Reihenfolge: validate → format → lint vor dem Merge

JSON-Validator allein reicht nicht — syntaktisch gültiges JSON kann ungültiges OpenAPI sein

OpenAPI-Spec validieren: Schritt-für-Schritt-Workflow

Den OpenAPI-Validator nutzen

Der OpenAPI-Validator parst die Eingabe (JSON oder YAML, max. 512 KiB) und ruft Scalar validate() auf. Ergebnis: Status, erster Fehler mit Zeile wenn bekannt, Issue-Liste mit JSON-Pointer-Pfaden.

Einzeldatei-Spec einfügen — kein externer URL-Fetch

Live debounced Validierung im Monaco-Editor

Ergebnispanel: Urteil, Scalar-Issues, Paths/Operations-Statistiken

https://…-Referenzen werden nie geladen — bewusste Einschränkung

Swagger 2.0 → klare Fehlermeldung, keine Teilvalidierung

Vor oder nach der Validierung formatieren

Der OpenAPI-Formatter pretty-printet JSON oder YAML (2 oder 4 Leerzeichen Einzug, optional Key-Sort). Nützlich für menschliche Reviews — ersetzt validate nicht.

Lesbares Format für PRs — Einrückung passend zum Team

Optional Key-Sort für stabile Diffs

Ungültige OpenAPI-Eingabe kann trotzdem formatiert werden, wenn Parse gelingt

Kette format → validate, um Fehler auf eingerückter Spec zu finden

Großes YAML: 512-KiB-Limit vor dem Einfügen prüfen

Szenario — Defekte Spec vor API-Gateway-Import

Sie exportieren eine Spec aus einem Design-Tool und AWS API Gateway / Kong-Import scheitert ohne Details.

Schritt 1: In validate-openapi einfügen

Öffnen Sie validate-openapi. Scheitert der Parse, zuerst JSON/YAML-Syntax korrigieren — der JSON-Validator hilft bei JSON-Anteilen.

Schritt 2: Interne $ref korrigieren

Scalar-Issues listen den Pfad (fehlendes #/components/schemas/User usw.). Tippfehler beheben oder referenzierte Komponente ergänzen.

Schritt 3: Formatieren und committen

Validierte Spec durch format-openapi laufen lassen, herunterladen, PR öffnen. Erneut ins Gateway importieren.

Szenario — Contract-Review vor SDK-Generierung

Das Mobile-Team generiert einen Client aus der Spec — ein Schemafehler blockiert die gesamte Pipeline.

Schritt 1: Gemergte Version validieren

Spec vom main-Branch in validate-openapi einfügen. Ungültiges Urteil → Release-Tag blockieren.

Schritt 2: info und paths prüfen

Vollständige info-Felder, jede Operation hat responses mit description. Statistiken im Ergebnispanel helfen, leere paths zu erkennen.

Schritt 3: Eingebettete JSON-Beispiele minifizieren

Große eingebettete Beispiele verlangsamen Reviews — nutzen Sie den JSON-Minifier auf Beispiel-Payloads nach validierter Spec.

Fazit

OpenAPI-Specs vor der CI zu validieren spart Stunden Debug bei Gateway-Imports oder stillen SDK-Generatoren. Einfügen, validieren, Scalar-Pfade korrigieren — alles lokal. Formatieren für das Review, dann API-Hub für Lint, JSON-Schema-Konvertierung und GraphQL-Validierung erkunden.

OpenAPI-Spec jetzt validieren

Vor jedem PR mit OpenAPI-Spec validieren

Dieses Tool nicht für Swagger 2.0 nutzen — zuerst migrieren

Externe $ref upstream bundeln für zuverlässige Browser-Validierung

validate → format → lint für vollständiges Review verketten

REST-JSON-Leitfaden für Payload-Optimierung nach gesundem Vertrag