OpenAPI: Linten, formatieren und eine wartbare API strukturieren

OpenAPI: Linten, formatieren und eine wartbare API strukturieren

operationId, Tags, Fehler-Responses: Regeln gegen Spec-Schulden, wenn Sie OpenAPI-Dateien online linten und formatieren.

09.08.2026
8 Min. Lektüre
Teilen Sie diesen Artikel:
openapilintformatapi-designAUSRUHENAnleitung

OpenAPI-Spezifikationen vor dem Merge linten und formatieren

Eine Spezifikation kann die Schema-Validierung bestehen und trotzdem ohne operationId, ohne tags oder nur mit einer default-Antwort ausgeliefert werden. Diese technische Schuld zeigt sich Wochen später, wenn SDK-Generatoren, API-Portale oder Contract-Tests still scheitern. Formatieren allein schließt diese Lücken nicht, Linting dagegen erkennt Stil- und Vollständigkeitsregeln, die Validatoren ignorieren. Der Online-OpenAPI-Linter von FastMinify wendet eine feste, an Spectral angelehnte Teilmenge auf Pfadoperationen an, vollständig im Browser. Kombinieren Sie ihn mit dem OpenAPI-Formatter für lesbare PR-Diffs und dem OpenAPI-Validator für die Schema-Konformität. Wenn zuerst strukturelle Fehler im Weg stehen, beginnen Sie mit unserem OpenAPI-Validierungsleitfaden und erkunden Sie danach den API-Tools-Hub.

Fehlende operationId, Tags und 2xx-Responses vor SDK- oder Portal-Generierung erkennen
Spectral-ähnliches Subset: info-contact, paths-kebab-case, operation-description und mehr
JSON oder YAML für stabile PR-Diffs formatieren, optional mit rekursiver Schlüsselsortierung
100 % lokal: Spezifikationen verlassen den Browser nicht, was zu internen Verträgen passt
Empfohlene Kette: validieren → formatieren → linten → Commit

Ehrliche Grenzen und wartbares API-Design

Was lint-openapi nicht tut

Ein Ergebnis Keine blockierenden Probleme bedeutet, dass das Regel-Subset v1 nichts beanstandet, nicht dass Ihre API produktionsreif oder vollständig dokumentiert ist.

Kein Sicherheitstest (Auth-Flows, Durchsetzung von Scopes)
Kein Contract-Testing zur Laufzeit gegen echte Endpoints
Kein automatisches Bündeln mehrerer Dateien: Fügen Sie bei jedem Durchlauf eine eigenständige Spezifikation ein
Keine Unterstützung für Swagger 2.0: nur OpenAPI 3.x
Warnungen blockieren kein Ergebnis „Gültig mit Warnungen“: Behandeln Sie sie als Merge-Blocker, wenn Ihre Teamrichtlinie das verlangt
operationId, Tags und Fehler-Responses

Diese Felder verhindern Spezifikationsschulden, die Validatoren übersehen, Generatoren und Portale aber verlangen.

operationId: stabil, eindeutig, camelCase und nie ohne Deprecation-Plan umbenannt
tags: Gruppierung nach Fachdomäne, passend zu den Abschnitten des Entwicklerportals
2xx-Antworten: Lint erzwingt ihr Vorhandensein, ergänzen Sie also ausdrückliche 400-, 401-, 404- und 500-Antworten mit Schemas, wo Clients sie brauchen
info.description und info.contact: Lint warnt, wenn sie fehlen, füllen Sie sie also für externe APIs aus
Pfadnamen: /pet-orders statt /petOrders, denn die kebab-case-Regel folgt den REST-Konventionen
Wann Sie auf CI-Werkzeuge umsteigen

Browser-Werkzeuge beschleunigen das Feedback, Pipelines erzwingen die Richtlinien der gesamten Organisation.

Benutzerdefinierte Spectral-Rulesets (Benennung, Security-Header, Paginierung)
Erkennung inkompatibler Änderungen zwischen Spezifikationsversionen
Bündeln von Spezifikationen aus mehreren Dateien mit Auflösung externer $ref
Validierung beim Import je Gateway (AWS API Gateway, Kong-Plugins)
Dokumentieren Sie die Ziel-OpenAPI-Version (3.0 oder 3.1, also der JSON-Schema-Draft) im README des Repositorys

Erst validieren, dann formatieren, dann linten (Design-first)

Drei Werkzeuge, drei Aufgaben

Vertauschen Sie die Schritte bei der Prüfung nicht: Jedes Werkzeug beantwortet eine andere Frage zu Ihrer OpenAPI-Datei.

Validate (validate-openapi): Konformität mit dem OpenAPI-3.x-Schema über Scalar, mit dem Ergebnis gültig oder ungültig
Format (format-openapi): Einzug und Lesbarkeit, ohne semantische oder stilistische Lücken zu schließen
Lint (lint-openapi): an Spectral angelehnte Regeln für Pfadoperationen, Warnungen und Fehler getrennt von der Schema-Validierung
Empfohlene Reihenfolge: validieren → formatieren → linten vor dem Merge
JSON-Syntax allein reicht nicht: Siehe den Validierungsleitfaden für Schema gegenüber Lint
Lint-Regeln in v1 (an Spectral angelehnte Teilmenge)

Das Lint von FastMinify ist nicht das vollständige Spectral. Es bringt ein festes Regelwerk für wartbare Pfadoperationen mit (ADR-OAS-009).

not-openapi (Fehler): Die Wurzel muss OpenAPI 3.x mit einem info-Objekt sein, als Eingangsprüfung vor den anderen Regeln
info-contact (Warnung): info.contact sollte vorhanden sein
info-description (Warnung): nicht leere info.description
paths-kebab-case (Warnung): Pfadsegmente in kebab-case oder vN
operation-operationId (Warnung): Jede Operation braucht eine nicht leere operationId
operation-tags (Warnung): mindestens ein Tag pro Operation
operation-description (Warnung): Summary oder Description erforderlich
operation-success-response (Fehler): mindestens eine 2xx-Antwort, default allein zählt nicht
path-item-ref (Warnung): $ref eines Path Items wird im Lint v1 nicht aufgelöst
Was Lint nicht abdeckt (v1)

Ein ehrlicher Umfang: Nehmen Sie keine Parität mit Spectral, Redocly oder Policy-Engines von Gateways an.

Nur Pfadoperationen: webhooks und callbacks sind in v1 nicht abgedeckt
Kein Upload eigener Rulesets: Die Teilmenge ist fest und kein Spectral-Runner
Lint ersetzt keine Schema-Validierung: Nutzen Sie validate-openapi für die Scalar-Konformität
Externe $ref-URLs werden nicht abgerufen: Fügen Sie eine eigenständige Spezifikation ein
Eingabegrenze von 512 KiB: Sehr große Spezifikationen gehören in die CI
Formatieren für die Prüfung, nicht für die Semantik

Der Formatter schreibt JSON oder YAML mit 2 oder 4 Leerzeichen Einzug neu und kann Schlüssel rekursiv für stabile Diffs sortieren.

JSON hinein ergibt JSON heraus, YAML hinein ergibt YAML heraus: Der Eingabetyp bleibt erhalten
YAML-Kommentare gehen beim Formatieren verloren: Sichern Sie annotierte Spezifikationen, bevor Sie sie neu formatieren
Ein numerisches openapi: 3.0 in YAML wird zum String 3.0.0 normalisiert
Das Sortieren der Schlüssel hilft bei der PR-Prüfung, ist aber keine Umordnung der Abschnitte mit Kenntnis von OpenAPI
Ungültiges OpenAPI lässt sich trotzdem formatieren, wenn das Einlesen gelingt: Validieren Sie nach größeren Änderungen erneut

OpenAPI Schritt für Schritt linten und formatieren

Den OpenAPI-Linter nutzen

Der OpenAPI-Linter liest JSON oder YAML ein (höchstens 512 KiB), prüft die Eingangsregel not-openapi und führt dann die Regeln für Pfadoperationen aus. Das Ergebnis lautet Keine blockierenden Probleme, Gültig mit Warnungen oder Blockierende Probleme gefunden und ist bei vorhandenen Warnungen nie einfach grün.

Live-Lint im Monaco-Editor nach kurzer Debounce-Pause
Problemliste mit Regelcode, Stufe und JSON-Pointer-Pfad
Ergebnispanel: Anzahl der Fehler und Warnungen sowie Statistiken zu Pfaden und Operationen
Einlesefehler erscheinen mit Zeilennummer, wenn sie bekannt ist
Swagger-2.0-Dokumente scheitern an der Regel not-openapi: Migrieren Sie zuerst auf OpenAPI 3
Den OpenAPI-Formatter nutzen

Der OpenAPI-Formatter schreibt das Dokument für die menschliche Prüfung neu. Er formatiert beim Einfügen automatisch, und die Schaltfläche Format (⌘↵) greift nach manuellen Änderungen.

Einzug von 2 oder 4 Leerzeichen, je nach Teamkonvention
Optionale rekursive Schlüsselsortierung für stabile Git-Diffs
Ausgabepanel mit Shiki-Hervorhebung
Verketten Sie format → validate → lint für einen vollständigen Durchlauf vor dem Merge
Kombinieren Sie ihn mit dem JSON-Validator, wenn die Rohsyntax fraglich ist
SDK-Generierung durch fehlende operationId blockiert

Ihre Mobile-Pipeline erzeugt einen Client aus der Spezifikation, und ignorierte Warnungen werden nachgelagert zu harten Fehlern.

1

Schema-Konformität validieren

Fügen Sie sie in validate-openapi ein. Beheben Sie zuerst die Scalar-Fehler, denn Lint hilft bei strukturell ungültigen Spezifikationen nicht.

2

Pfadoperationen linten

Öffnen Sie lint-openapi. Beheben Sie die Warnungen operation-operationId und operation-tags auf jedem öffentlichen Endpoint.

3

Formatieren und PR öffnen

Schicken Sie die korrigierte Spezifikation durch format-openapi, mit Schlüsselsortierung, wenn Ihr Team stabile Diffs nutzt. Lassen Sie vor dem Commit den Lint erneut laufen.

Ein unlesbarer YAML-Diff bei der Vertragsprüfung

Ein Designer exportiert minifiziertes YAML, und die Prüfenden erkennen versehentliche Umbenennungen von Pfaden nicht.

1

Für die Lesbarkeit formatieren

Fügen Sie das Dokument in format-openapi ein, wählen Sie 2 Leerzeichen Einzug und aktivieren Sie die Schlüsselsortierung, wenn das Team einverstanden ist.

2

Validieren, dann linten

Validieren Sie mit Scalar und prüfen Sie dann neue Endpoints per Lint auf paths-kebab-case und operation-success-response.

3

Fehlerantworten dokumentieren

Lint erzwingt das Vorhandensein einer 2xx-Antwort. Ergänzen Sie 4xx- und 5xx-Antworten mit Beschreibungen von Hand für produktionsreife Verträge, denn die Fehler des Lint v1 decken sie nicht ab.

PR-Review vom Design-first bis zum Merge

Empfohlene Checkliste vor dem Merge

Behandeln Sie das Browser-Trio als schnelle Schranke vor git push. Die CI bleibt die maßgebliche Instanz des Teams, aber lokales Erkennen spart Pipeline-Minuten. Starten Sie mit validate-openapi für die Scalar-Fehler, dann format-openapi für einen lesbaren Diff. Schließen Sie mit lint-openapi ab, um Fehler und dann Warnungen nach Teamrichtlinie zu beheben, und checken Sie es ein.

Schwerpunkte für die Prüfenden

Fragen Sie über ein grünes Validate hinaus, ob die operationId-Werte für Codegen eindeutig und stabil sind. Fragen Sie, ob die Tags zur Navigation des API-Portals passen und ob jede Operation mindestens eine Erfolgsantwort dokumentiert. Fragen Sie auch, ob gängige Fehlerformen für Client-Teams beschrieben sind.

Mit CI und verwandten Werkzeugen kombinieren

In der CI laufen oft Spectral, openapi-cli oder Redocly mit strengeren Rulesets als in FastMinify v1. Kombinieren Sie das Browser-Lint mit unserem CI/CD-Automatisierungsleitfaden. Für den Wechsel zwischen Schema-Formaten nutzen Sie json-schema-to-openapi und openapi-to-json-schema im Hub. Um Payloads gegen ein Schema zu validieren, sobald der Vertrag steht, lesen Sie unseren JSON-Schema-Validierungsleitfaden.

Zusammenfassung

Wartbare OpenAPI-Spezifikationen brauchen mehr als Schema-Validierung. Lint erkennt die Lücken bei operationId, Tags und Antworten, die Generatoren blockieren, und Formatieren hält PRs prüfbar. Validieren Sie zuerst, formatieren Sie für Menschen und linten Sie für den Stil, alles lokal vor der CI. Erkunden Sie den API-Hub für JSON-Schema-Konvertierung und GraphQL-SDL-Validierung, wenn Ihre Vertragsarbeit über REST hinausgeht.

Linten und formatieren Sie Ihre OpenAPI-Spezifikation jetzt

Vor jeder PR zur Spezifikation: validieren → formatieren → linten
Behandeln Sie Lint-Warnungen als Merge-Blocker, wenn die SDK-Generierung im Spiel ist
Aktivieren Sie die Schlüsselsortierung nur, wenn das ganze Team einverstanden ist, denn sie verändert die Semantik der Diffs
Lesen Sie den Validierungsleitfaden erneut, wenn Scalar-Fehler auftreten, bevor Sie den Lint auf Fehler untersuchen
Steigen Sie für organisationsspezifische Regeln über das v1-Subset hinaus auf Spectral oder Redocly in der CI um
Teilen Sie diesen Artikel
Teilen Sie diesen Artikel: