OpenAPI Linting

In größeren API-Landschaften zeigt sich früher oder später ein vertrautes Muster. OpenAPI-Specs unterscheiden sich von Team zu Team in Details, die nie bewusst festgelegt wurden. Einige Endpunkte verwenden camelCase, andere snake_case oder kebab-case. Authentifizierung wird unterschiedlich modelliert. Versionierung steht mal im Pfad, mal im Header und mal im Accept-Header.

Meist steckt dahinter keine bewusste Entscheidung, sondern das Fehlen einer verbindlichen Systematik. Wenn Style Guides nicht nur dokumentiert, sondern automatisch durchgesetzt werden sollen, führt an OpenAPI Linting kaum ein Weg vorbei. Mit einem Linter wird die Spec anhand eines konfigurierbaren Regelwerks geprüft, und Findings erscheinen direkt im Pull Request, noch bevor Code gemergt wird. Entscheidend ist dabei weniger die Tool-Auswahl. Wichtiger ist die Frage, was die Regeln fachlich prüfen sollen.

Wofür Linting-Rules eigentlich da sind

In vielen Organisationen, die OpenAPI ernsthaft nutzen, gibt es einen Style Guide. Er liegt auf einer Confluence-Seite, enthält zwölf bis vierzig Regeln, ist sauber formuliert und wird durchaus gelesen. Nur wird er im Alltag nicht immer zuverlässig angewendet. Eine Regel zu camelCase ist schnell vergessen, wenn der Termindruck steigt und der nächste Endpunkt Felder einer alten Drittsystem-API mit kebab-case übernehmen muss.

Ein zweites Problem zeigt sich, sobald die API-Landschaft wächst. Reviews durch erfahrene API-Architekten funktionieren gut, solange ein Team nur wenige APIs betreut. Bei fünfzig APIs werden sie schnell zum Engpass. Der Review wandert dann entweder in eine Warteschleife oder findet im Zweifel gar nicht mehr statt. Was eigentlich Qualität sichern soll, wird dadurch zu einem Bottleneck, das Releases ausbremst.

Das dritte Problem ist besonders kritisch, weil es oft lange unbemerkt bleibt. Sicherheitslücken wie ein fehlender Auth-Block, eine nicht definierte Rate-Limit-Policy oder sensitive Datenstrukturen in URLs werden in Code-Reviews häufig übersehen. Wer eine Spec manuell gegen eine Confluence-Seite prüft, achtet meist auf Naming-Inkonsistenzen, aber selten systematisch auf security: []-Einträge mit leerem Array.

In der Praxis kehren damit drei Muster wieder:

• dokumentierte Style-Guides, die im Alltag inkonsistent angewendet werden,
• manuelle Reviews, die ab einer bestimmten API-Anzahl zum Engpass werden,
• sicherheitsrelevante Lücken, die in menschlichen Prüfungen häufig durchrutschen.

Genau hier setzt OpenAPI Linting an. Der Style Guide wird mit einem Linter nicht ersetzt, sondern ausführbar gemacht. Was im Wiki noch wie eine Empfehlung wirkt, wird im Pull Request zu einer klaren, reproduzierbaren Prüfung mit Zeilenreferenz und Korrekturhinweis.

Dadurch verändert sich auch die Rolle der Reviewer in der API-Architektur. Wer vorher in jedem Pull Request dieselben Naming-Hinweise wiederholt hat, kann sich nun auf die fachlich wichtigeren Fragen konzentrieren. Passt das Datenmodell zum Geschäftsprozess? Ist die Versionierungs-Strategie konsistent mit dem Rest der Plattform? Solche Fragen bekommen im Review erst dann wirklich Raum, wenn der Linter die wiederkehrenden mechanischen Prüfungen bereits übernommen hat.

Vier Kategorien fachlicher Prüfungen

Linter-Regeln lassen sich in der Praxis gut in vier Kategorien einteilen. Jede Kategorie beantwortet eine andere fachliche Frage. Style-Regeln prüfen Konsistenz und Lesbarkeit. Security-Regeln verhindern, dass zentrale Schutzmechanismen fehlen. Performance-Regeln unterstützen Skalierbarkeit und Ressourcen-Effizienz. Compliance-Regeln bilden branchenspezifische Vorgaben ab.

Die folgende Tabelle ordnet die Kategorien nach typischen Beispielen und treibender Rolle.

Viele Teams starten mit Style- und Security-Regeln, weil die größten Reibungsverluste dort besonders schnell sichtbar werden. Performance- und Compliance-Regeln folgen häufig später, wenn das Linting etabliert ist und das Team Vertrauen in den Prozess aufgebaut hat.

In regulierten Branchen sieht die Reihenfolge oft anders aus. Wer im Banking, Healthcare- oder Automotive-Umfeld APIs entwickelt, kommt an Compliance-Regeln nicht vorbei. Vorgaben wie PSD2, HL7 FHIR oder UNECE R155 sind dort keine spätere Ergänzung, sondern Teil der Grundanforderungen. In solchen Bereichen gehören Compliance-Regeln deshalb von Anfang an in das Linter-Setup.

Eine Erfahrung zeigt sich dabei branchenübergreifend. Teams, die alle vier Kategorien gleichzeitig vollständig abdecken wollen, verlieren sich häufig in Konfigurationsdiskussionen. Teams, die zunächst mit Style-Regeln starten und nach einigen Sprints Security-Regeln ergänzen, kommen meist schneller in einen produktiven Linter-Betrieb. Die Reihenfolge ist dabei oft wichtiger als der Anspruch, von Beginn an alles abzudecken.

Style-Regeln in der Praxis

Style-Regeln bilden in vielen Linter-Konfigurationen den größten Anteil. Sie sorgen dafür, dass eine API-Landschaft konsistent bleibt, auch wenn mehrere Teams parallel daran arbeiten. Fünf Themenfelder finden sich in nahezu jedem Style Guide wieder.

Naming-Konventionen. Properties verwenden camelCase, Pfad-Segmente kebab-case. Collection-Resources stehen im Plural, Item-Resources im Singular. Ergänzt man eine klare Konvention für Path-Parameter, etwa {customerId} statt {customer_id}, entsteht eine Spec, die auch ohne zusätzlichen Kontext gut lesbar bleibt.

Pfad-Struktur. Eine REST-konforme Hierarchie, keine Verben im Pfad und eine klare Schachtelung von Sub-Ressourcen schaffen Orientierung. Aus POST /createOrder wird POST /orders. Aus GET /getOrderByCustomerId/{id} wird GET /customers/{id}/orders. Diese Regeln sind etabliert, werden im Projektalltag aber trotzdem regelmäßig verletzt.

Operations-Disziplin. Jede Operation braucht eine operationId, weil sie für die SDK-Generation eindeutig sein muss. tags strukturieren die Dokumentation, summary und description machen die Spec für Menschen lesbar. Fehlen diese Felder, erzeugen Code-Generatoren und Dokumentations-Tools eigene Defaults, die selten zur gewünschten API-Dokumentation passen.

Schema-Konsistenz. Datums- und Zeitwerte werden als date-time modelliert, nicht als freie Strings. Enum-Werte bleiben einheitlich geschrieben, also durchgehend UPPERCASE oder durchgehend lowercase, aber nicht gemischt. Required-Felder werden explizit deklariert. Solche Regeln verhindern subtile Fehler im Konsumenten-Code, die sonst oft erst zur Laufzeit auffallen.

Error-Format. Eine einheitliche Konvention für Fehler-Responses ist wichtig, in vielen Fällen auf Basis von RFC 9457 Problem Details. Wenn jedes Team ein eigenes Error-JSON modelliert, müssen Konsumenten am Ende mehrere unterschiedliche Error-Handler implementieren.

Security-Regeln in der Praxis

Security-Regeln folgen in vielen Teams direkt nach den Style-Regeln. Sie schließen Lücken, die in Code-Reviews leicht übersehen werden. Menschliche Reviewer achten oft auf Naming, Struktur und Lesbarkeit, aber nicht immer systematisch auf das Vorhandensein eines Auth-Blocks.

Auth-Schema-Pflicht. Jeder Endpunkt braucht ein deklariertes Security-Scheme. Ein leerer security: []-Block oder ein fehlendes security-Feld können darauf hinweisen, dass ein Endpunkt unbeabsichtigt offen ist. Mit Linter-Regeln werden solche Stellen sofort sichtbar, auch in großen Specs mit fünfzig oder mehr Endpunkten.

HTTPS-only. servers-URLs sollten ausschließlich https:// verwenden. HTTP-Fallbacks gehören nicht in produktive OpenAPI-Specs, weder als Default noch als alternative Server-URL. Wer beides modelliert, überlässt Konsumenten oder Tooling eine Sicherheitsentscheidung, die eigentlich zentral getroffen werden sollte.

Sensitive Daten nicht in URLs. Query-Parameter wie ?api_key=…​ oder ?password=…​ sind ein Logging-Risiko und können im Audit zum Problem werden. Auch personenbezogene IDs als Path-Parameter sollten aus DSGVO-Sicht geprüft werden, insbesondere wenn URLs in Webserver-Logs landen.

Rate-Limiting-Konventionen. Header wie X-RateLimit-Limit und X-RateLimit-Remaining sind kein Pflichtbestandteil von OpenAPI, sollten in einer durchdachten Style-Guide-Konfiguration aber als Pflicht oder Empfehlung definiert werden. Ohne diese Informationen können Konsumenten nicht sinnvoll auf Limits reagieren oder ihre Requests kontrolliert reduzieren.

OWASP API Top 10 Coverage. Mindestens BOLA, Broken Authentication und Excessive Data Exposure sollten als Standard-Checks berücksichtigt werden. Die OWASP API Top 10 deckt zentrale Risiken ab, von denen insbesondere die ersten Kategorien in vielen API-Audits wiederkehren.

Engines und Standard-Rulesets im Überblick

Welche Linter-Engine eingesetzt wird, ist fachlich meist zweitrangig. Die meisten Engines können ähnliche fachliche Regeln abbilden, unterscheiden sich aber in Syntax, Performance und Integrationsmöglichkeiten. Wichtiger als die Engine ist deshalb das Ruleset, das damit ausgeführt wird.

Spectral von Stoplight ist eine der verbreitetsten Open-Source-Engines, mit großer Community und vielen verfügbaren Rulesets. Vacuum ist eine performance-orientierte Alternative, besonders für sehr große Specs. Plattform-eigene Linter wie der von api-portal.io bringen vorbereitete Regeln und Branchen-Pakete mit, die sonst manuell zusammengestellt und gepflegt werden müssten.

Auf der Ruleset-Seite haben sich mehrere Standards etabliert, die in vielen professionellen Linter-Setups wiederzufinden sind.

• Zalando RESTful API Guidelines. Mit über 170 Regeln sind sie im DACH-Raum für viele Teams ein wichtiger Referenzpunkt. Sie decken unter anderem Style, Versionierung, Pagination und weitere API-Design-Themen ab.
• Google Cloud API Design Guide. Der Fokus liegt auf REST-Konventionen für große verteilte Systeme, mit besonderem Blick auf Skalierbarkeit und Konsistenz.
• Microsoft Azure API Guidelines. Ähnlich wie bei Google stehen konsistente API-Konventionen im Mittelpunkt, ergänzt um klare Empfehlungen zu Versionierung und Deprecation-Mustern.
• OWASP API Security Top 10. Dieses Ruleset ergänzt Style-orientierte Ansätze um sicherheitsrelevante Prüfungen.

In vielen Teams hat sich ein pragmatischer Einstieg bewährt. Zunächst mit einem etablierten Style-Ruleset wie Zalando starten, anschließend OWASP für Security ergänzen und eigene Regeln nur dort definieren, wo das Geschäftsmodell oder interne Plattform-Konventionen es wirklich erfordern. Branchen-Rulesets für PSD2, HL7 FHIR oder UNECE R155 entstehen entweder aus Industrie-Initiativen oder werden plattformseitig gepflegt. Wer in einem dieser Bereiche arbeitet, sollte deshalb zuerst prüfen, welche Regeln bereits existieren, bevor eigene Compliance-Regeln aufgebaut werden.

Wichtig ist die klare Trennung zwischen Engine-Auswahl und Ruleset-Auswahl. Engines werden meist nur im Rahmen größerer Plattform-Migrationen gewechselt. Rulesets entwickeln sich dagegen kontinuierlich weiter, weil neue Regulierungen, OWASP-Versionen oder interne Konventionen hinzukommen. Wer das Linter-Setup als lebendes System versteht, behandelt die Engine als stabile technische Basis und das Ruleset als versioniertes Artefakt, das aktiv gepflegt wird.

Severity, Quality Score und CI/CD-Integration

Auch das beste Linter-Setup verliert an Wirkung, wenn die Severity-Strategie nicht sauber durchdacht ist. Vier Levels haben sich bewährt. error blockiert den Merge, warn weist im Pull Request auf Findings hin, ohne zu blockieren, info eignet sich für Hygiene-Themen und hint für Vorschläge mit niedriger Priorität.

Bei der Einführung ist die Vorgehensweise oft wichtiger als die perfekte initiale Konfiguration. Wer alle Regeln direkt auf error setzt, blockiert schnell bestehende Pull Requests und riskiert Widerstand im Team. Sinnvoller ist es, neue Regeln zunächst auf warn zu setzen und pro Sprint gezielt einzelne Regeln auf error hochzustufen. So erreicht das Linter-Setup nach einigen Monaten einen konsistenten Stand, ohne dass eine große Crisis-Migration notwendig wird.

Der Quality Score ist die zweite wichtige Säule der Operationalisierung. Aus den Findings pro Spec entsteht eine gewichtete Bewertung, die über die Zeit verfolgt werden kann. Dadurch wird Linter-Adoption messbar, und Teams sehen, wie sich ihre Spec-Qualität im Vergleich zum Vorquartal entwickelt.

Drei Integrationsstufen decken den API-Lifecycle sinnvoll ab. Lokal unterstützt ein Pre-Commit-Hook die Entwickler bereits vor dem Push. Im Pull Request prüft eine CI-Stage mit Block-Funktion. Nach dem Merge sorgt ein Post-Merge-Tracking dafür, dass der Quality Score sichtbar bleibt. Native Plugins für GitHub Actions, GitLab CI und Jenkins können Findings als Inline-Kommentare mit Zeilenreferenz ausgeben. Das beschleunigt die Korrektur deutlich.

Wie api-portal.io OpenAPI Linting umsetzt

api-portal.io bringt über 150 Linter-Regeln out-of-the-box mit. Sie sind in die Bereiche Style, Security, Performance und Compliance gegliedert. Branchenspezifische Rule-Packs decken unter anderem PSD2, HL7 FHIR und UNECE R155 ab und werden kontinuierlich weiterentwickelt.

Der Quality Score wird pro Spec inklusive Verlauf getrackt. Teams können dadurch nachvollziehen, wie sich ihre Spec-Qualität über die Zeit entwickelt.

Der API Linter prüft API-Specs automatisiert gegen definierte Qualitätsregeln und macht Findings dort sichtbar, wo sie am wirksamsten behoben werden können, im Entwicklungs- und Review-Prozess.