Eine OpenAPI-Spec ist ein Vertrag, den vor allem Maschinen lesen. OpenAPI Best Practices regeln, wie dieser Vertrag geschrieben sein muss, damit Generatoren, Gateways und Portale ihn richtig verstehen. Der Codegenerator macht aus jeder operationId einen Methodennamen, und das Gateway setzt die Security Schemes durch, die in der Spec stehen. Das Developer Portal baut seine Navigation aus den Tags, während ein Diff-Tool an den Schemas abliest, ob eine Änderung Konsumenten bricht. Für diese Tools genügt es nicht, dass eine Spec gültig ist. Dass eine Spec gegen das OpenAPI-Schema validiert, heißt nur, dass sie formal korrekt ist, und sagt wenig über ihre Qualität aus. Ob ein Generator daraus brauchbaren Code erzeugt, bleibt dabei offen.

Wie viel Gewicht eine Regel hat, hängt davon ab, welches Tool sich auf sie verlässt. An erster Stelle stehen stabile Operation IDs und präzise Schemas, weil ein Fehler dort generierte Clients und Contract Tests unbrauchbar macht. Der Benennungsstil zählt dagegen vor allem für Entwickler, die mit der Dokumentation arbeiten. Für den Alltag ist außerdem entscheidend, ob ein Linter eine Regel prüfen kann oder ob es dafür einen Reviewer braucht. Schreiben Dutzende Teams Specs, werden auf Dauer vor allem die Regeln eingehalten, die ein Linter automatisch prüft.

Hinweis

Die zwölf OpenAPI Best Practices in diesem Ratgeber betreffen Aufbau, Operationen, Schemas, Fehler und Security sowie Änderungen an der Spec. Zu jeder Regel steht, für wen sie wichtig ist (Codegenerator, Gateway, Developer Portal oder Entwickler) und ob sie sich automatisch prüfen lässt. Alle YAML-Beispiele folgen OpenAPI 3.1 und sind auf die Felder gekürzt, um die es in der jeweiligen Regel geht.

Die Checkliste der OpenAPI Best Practices

Die Tabelle fasst alle zwölf Regeln zusammen. In der letzten Spalte steht, ob sich die Regel automatisch prüfen lässt. Davon hängt ab, ob sie in die Pipeline gehört oder ins Review.

Nr.RegelWichtig fürAutomatisch prüfbar
1OpenAPI-Version bewusst wählenCodegenerator, Gateway, Developer PortalTeilweise
2Einmal unter components definieren und per $ref referenzierenCodegenerator, Developer PortalTeilweise
3Ressourcen aus der Fachsprache der Konsumenten benennen, in einem CasingEntwickler im Portal, generierte ClientsTeilweise
4Jeder Operation eine eindeutige, stabile operationId gebenCodegeneratorJa
5Operationen mit Tags nach Fachdomänen gruppierenDeveloper Portal, CodegeneratorTeilweise
6Summary und Description für Konsumenten schreibenEntwickler im PortalTeilweise
7Schemas so eng fassen, wie der Vertrag es erlaubtCodegenerator, Contract TestsTeilweise
8Beispiele schreiben, die gegen ihr Schema validierenDeveloper Portal, Mock-ServerJa
9Nullbarkeit und Polymorphie ausdrücklich modellierenCodegeneratorTeilweise
10Error Responses als gemeinsame Komponente festlegenError Handling im ClientJa
11Security Schemes und Scopes je Operation angebenGateway, ClientJa
12Deprecations markieren und jede Änderung auf Breaking Changes prüfenAlle KonsumentenJa

Wie sollte ein OpenAPI-Dokument aufgebaut sein?

Der Aufbau eines OpenAPI-Dokuments beginnt mit der Wahl der OpenAPI-Version, die Generator, Gateway und Portal unterstützen müssen. Danach folgen wiederverwendbare Bausteine unter components und Ressourcennamen aus der Fachsprache der Konsumenten. Alle drei Entscheidungen lassen sich später nur mit viel Aufwand ändern, weil jeder generierte Client und jede Portalseite darauf aufbaut.

1. OpenAPI-Version bewusst wählen

In größeren Organisationen laufen oft mehrere OpenAPI-Versionen nebeneinander, von 3.0 bis 3.2. Mit 3.1 wurde das Schema Object an JSON Schema 2020-12 angeglichen. Dadurch schreibt man Nullbarkeit anders und kann vorhandene JSON Schemas direkt wiederverwenden. Version 3.2 bringt hierarchische Tags, die QUERY-Methode und Streaming, wie OpenAPI 3.2 und seine Neuerungen zeigt. Für die Wahl der Version zählt trotzdem vor allem, was das Tooling verarbeiten kann.

Bevor ein Team die Version anhebt, prüft es, ob Codegenerator, Gateway und Portal die Zielversion lesen können. Ein neues Feature bringt wenig, wenn danach eines der eingesetzten Tools die Spec nicht mehr korrekt verarbeitet. Welche OpenAPI-Versionen zugelassen sind, legt das Plattform-Team fest. Ein Linter sorgt anschließend dafür, dass keine Spec im Feld openapi einen anderen Wert trägt. Stammt ein Teil des Bestands noch aus der Swagger-Zeit, hilft OpenAPI vs Swagger bei der Einordnung.

2. Einmal unter components definieren und per $ref referenzieren

Was in mehr als einer Operation vorkommt, gehört unter components und wird mit $ref eingebunden. Das gilt für Schemas ebenso wie für Parameter und Responses. Der Generator erzeugt dann genau eine Klasse Order für alle Operationen, und eine Änderung am Schema wirkt überall zugleich. Inline-Schemas sind für Strukturen in Ordnung, die genau einmal vorkommen, etwa ein kleiner Request Body für eine einzelne Aktion.

yaml
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The order with all line items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: string
        format: uuid

Ein Linter kann Inline-Objektschemas in Responses melden. Ob zwei ähnliche Strukturen dasselbe fachliche Konzept beschreiben, entscheidet der Reviewer.

3. Ressourcen aus der Fachsprache der Konsumenten benennen, in einem Casing

Namen in einer Spec stammen aus der Fachsprache der Konsumenten. Das betrifft Pfade, Parameter und Properties gleichermaßen. Ein Pfad wie /customers/{customerId}/contracts sagt einem Entwickler beim Partner deutlich mehr als /kd_stamm/{id}/vtr, der eine Datenbanktabelle abbildet. Ein Style Guide legt außerdem für jeden Elementtyp eine Schreibweise fest, zum Beispiel kebab-case für Pfadsegmente und camelCase für Properties und Parameter.

Gemischtes Casing landet in jedem generierten Client. Sobald der erste Konsument live ist, lässt es sich kaum noch korrigieren, weil jede Umbenennung dann ein Breaking Change ist. Das Casing prüft ein Linter zuverlässig. Ob ein Name aus der Fachsprache stammt oder aus einem internen System, kann dagegen nur ein Reviewer beurteilen.

Was macht Operationen gut generierbar und dokumentierbar?

Eine Operation lässt sich gut generieren und dokumentieren, wenn sie eine stabile operationId, einen fachlichen Tag und eine aussagekräftige Beschreibung hat. Der Generator braucht die operationId für den Methodennamen, das Portal den Tag für die Navigation, und Entwickler brauchen die Beschreibung für die Integration.

4. Jeder Operation eine eindeutige, stabile operationId geben

Die operationId wird in generierten SDKs zum Methodennamen, etwa ordersApi.getOrder(). Fehlt sie, leiten Generatoren den Namen aus Pfad und Methode ab, und es entstehen Namen wie ordersOrderIdGet. Ändert sie sich, kompiliert der Code der Konsumenten nach dem nächsten Generieren nicht mehr, obwohl der HTTP-Vertrag genau gleich geblieben ist.

Die operationId ist damit Teil des Vertrags, auch wenn sie in keinem HTTP-Request vorkommt. Die Spezifikation verlangt ohnehin, dass sie über alle Operationen der API eindeutig ist. Teams legen zusätzlich ein Namensmuster fest, meist Verb plus Substantiv in camelCase, und ändern eine bestehende ID nur mit einer neuen Major-Version. Eindeutigkeit und Muster prüft der Linter bei jedem PR, und eine Umbenennung zeigt der Spec-Diff, den Regel 12 beschreibt.

5. Operationen mit Tags nach Fachdomänen gruppieren

Aus den Tags entsteht die Navigation im Developer Portal, und viele Generatoren erzeugen eine Client-Klasse je Tag. Mit Tags nach Fachdomänen wie Orders, Payments oder Customers finden Konsumenten im Portal und im generierten Client die Struktur vor, die sie aus dem Fachbereich kennen. Tags nach Teams oder Microservices bilden dagegen das Organigramm ab, und das ändert sich meist schneller als die Fachdomäne.

Tags werden auf oberster Ebene mit Beschreibung deklariert, und jede Operation trägt genau einen Tag, damit sie im Portal an genau einer Stelle erscheint. Für große APIs bringt OpenAPI 3.2 das Feld parent für verschachtelte Tags mit. Ein Linter prüft, ob jeder Tag deklariert und beschrieben ist. Ob die Struktur zur Fachdomäne passt, bleibt eine Frage für das Review.

6. Summary und Description für Konsumenten schreiben

Die summary erscheint in der Navigation des Portals und passt in eine Zeile. Die description enthält, was der Pfad nicht ausdrücken kann, also Verhalten, Seiteneffekte, Idempotenz, Vorbedingungen und Limits. Eine Description wie „Liefert eine Bestellung“ wiederholt nur, was GET /orders/{orderId} bereits sagt. „Liefert die Bestellung mit allen Positionen, auch stornierte Bestellungen bleiben abrufbar“ nennt dagegen ein Verhalten, das der Pfad nicht verrät.

Descriptions unterstützen CommonMark, sodass auch kurze Listen und Links auf Anleitungen möglich sind. Ein Linter prüft, ob beide Felder vorhanden sind und eine Mindestlänge haben. Ob der Text einem Konsumenten weiterhilft, klärt das Review.

Wie präzise sollten OpenAPI-Schemas sein?

Ein Schema sollte genau die Einschränkungen enthalten, die der Anbieter der API dauerhaft garantieren kann. Auf jede Einschränkung dürfen sich Konsumenten verlassen, und Contract Tests prüfen die Implementierung dagegen. Fehlt eine Einschränkung, trifft jeder Konsument seine eigene Annahme.

7. Schemas so eng fassen, wie der Vertrag es erlaubt

OpenAPI bietet für die gängigen Einschränkungen ein eigenes Schlüsselwort. Pflichtfelder stehen in required, und ein format kennzeichnet Datumswerte, UUIDs und E-Mail-Adressen. Für geschlossene Wertemengen gibt es enum, und wo das Backend ohnehin ein Limit hat, machen maxLength oder maximum es sichtbar. Das folgende Schema für eine Bestellung nutzt diese Einschränkungen und enthält ein Beispiel auf Schema-Ebene.

yaml
components:
  schemas:
    Order:
      type: object
      required: [id, status, createdAt, items]
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, confirmed, shipped, cancelled]
        createdAt:
          type: string
          format: date-time
        note:
          type: [string, 'null']
          maxLength: 500
        items:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/OrderItem'
      examples:
        - id: 7f3c2a9e-5b1d-4c8e-9f20-3a6b8d1e4c57
          status: confirmed
          createdAt: '2026-11-18T09:30:00Z'
          note: null
          items:
            - sku: AP-1001
              quantity: 2
    OrderItem:
      type: object
      required: [sku, quantity]
      properties:
        sku:
          type: string
          maxLength: 40
        quantity:
          type: integer
          minimum: 1

Bei additionalProperties lohnt eine bewusste Entscheidung. Steht es in einem Request-Schema auf false, fängt das Gateway falsch geschriebene Felder früh ab. In einem Response-Schema macht dieselbe Einstellung jedes neue Feld zum Breaking Change für Clients, die streng validieren. Viele Teams schließen deshalb Request-Schemas und lassen Response-Schemas offen. Ähnlich riskant sind Enums in Responses, weil ein neuer Wert jeden Client bricht, der nur die bekannten Werte behandelt. Der Style Guide legt deshalb fest, ob Konsumenten unbekannte Werte tolerieren müssen.

Ein Linter kann required, format und Längenlimits für Strings verlangen. Welche Grenzwerte fachlich richtig sind, kann nur ein Reviewer beurteilen.

8. Beispiele schreiben, die gegen ihr Schema validieren

Beispiele werden an drei Stellen direkt verwendet. Das Portal zeigt sie an, Mock-Server liefern sie aus, und Try-it-Konsolen füllen Requests damit vor. Widerspricht ein Beispiel seinem Schema, übernehmen Konsumenten den Fehler, weil sie Beispiele eher kopieren als Schemas lesen. In OpenAPI 3.1 ist examples im Schema Object ein Array, wie es das Schema Order in Regel 7 zeigt. Auf Ebene des Media Type zeigen benannte examples mit summary weitere Fälle, etwa eine stornierte Bestellung.

Ob jedes Beispiel zu seinem Schema passt, lässt sich automatisch prüfen, und genau das gehört in die Pipeline. Im Linter kostet die Regel wenig, und im Review muss danach niemand mehr Beispiele von Hand gegen das Schema prüfen.

9. Nullbarkeit und Polymorphie ausdrücklich modellieren

Optional und nullable bedeuten Verschiedenes. Ein optionales Feld darf im Dokument fehlen, während ein nullable Feld neben seinem eigentlichen Typ auch den Wert null annehmen darf. In OpenAPI 3.1 gehört die Nullbarkeit zum Typ, wie type: [string, 'null'] beim Feld note im Schema Order aus Regel 7 zeigt. Das Schlüsselwort nullable: true aus 3.0 hat in 3.1 keine Wirkung mehr. Nach einer Migration bleibt es trotzdem häufig stehen, weil die Validierung es als unbekanntes Schlüsselwort ignoriert. Das Feld gilt dann nicht mehr als nullable, und ein streng validierender Client weist den Wert null zurück.

Für polymorphe Payloads erlaubt oneOf zusammen mit einem discriminator den Generatoren, echte Untertypen zu erzeugen. Ohne Discriminator weichen viele Generatoren auf ein allgemeines Objekt oder eine Map aus, und der Konsument muss den Typ zur Laufzeit selbst herausfinden.

yaml
components:
  schemas:
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CardPayment'
        - $ref: '#/components/schemas/SepaPayment'
      discriminator:
        propertyName: type
        mapping:
          card: '#/components/schemas/CardPayment'
          sepa: '#/components/schemas/SepaPayment'
    CardPayment:
      type: object
      required: [type, last4]
      properties:
        type:
          const: card
        last4:
          type: string
          pattern: '^[0-9]{4}$'
    SepaPayment:
      type: object
      required: [type, iban]
      properties:
        type:
          const: sepa
        iban:
          type: string
          maxLength: 34

Ein Linter findet nullable in 3.1-Dokumenten und oneOf ohne Discriminator. Ob eine Payload überhaupt polymorph sein sollte, entscheidet das Team beim Entwurf der API.

Wie werden Fehler und Security beschrieben?

Fehler und Security gehören in gemeinsame Komponenten, die jede Operation referenziert. Dadurch behandeln das Gateway, der generierte Client und die Dokumentation im Portal Fehler und Berechtigungen bei jeder Operation auf dieselbe Weise.

10. Error Responses als gemeinsame Komponente festlegen

RFC 9457 (Problem Details for HTTP APIs) legt ein gemeinsames Fehlerformat mit den Feldern type, title, status, detail und instance sowie dem Media Type application/problem+json fest. Verweist jede Operation auf dieses Format, kommt jeder Konsument mit einem einzigen Error Handler aus. Nötig sind dafür ein gemeinsames Schema und je eine Response-Komponente für die üblichen Statuscodes. Validierungsfehler können das Format um eine Liste der betroffenen Felder erweitern.

yaml
components:
  schemas:
    Problem:
      type: object
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
  responses:
    NotFound:
      description: The resource does not exist or is not visible to the caller.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'

Ein Linter prüft, ob jede Operation ihre 4xx-Responses angibt und ob diese auf das gemeinsame Format verweisen.

11. Security Schemes und Scopes je Operation angeben

Security Schemes werden einmal unter components definiert. Das Feld security auf oberster Ebene setzt daraus einen Standard für alle Operationen, den einzelne Operationen mit eigenen Scopes überschreiben. Der Scope an der Operation sagt dem Gateway, was es durchsetzen soll, und dem Konsumenten, welche Berechtigung er beantragen muss. Öffentliche Endpoints geben security: [] ausdrücklich an, damit ein Reviewer einen bewusst offenen Endpoint von einem vergessenen unterscheiden kann.

yaml
security:
  - oauth: [orders:read]
paths:
  /orders:
    post:
      operationId: createOrder
      tags: [Orders]
      security:
        - oauth: [orders:write]
      responses:
        '201':
          description: The order was created.
  /health:
    get:
      operationId: getHealth
      tags: [Operations]
      security: []
      responses:
        '200':
          description: The service is available.
components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth2/token
          scopes:
            orders: read: Read orders
            orders: write: Create and change orders

Der Linter prüft, ob jede Operation durch ein Scheme abgedeckt ist und ob schreibende Operationen einen Schreib-Scope verlangen.

Wie ändert man eine Spec ohne Breaking Changes für Konsumenten?

Eine Spec lässt sich gefahrlos ändern, wenn das Team wegfallende Teile rechtzeitig als deprecated markiert und die Pipeline jede Änderung mit der zuletzt veröffentlichten Version vergleicht. Breaking Changes passieren meist aus Versehen, etwa durch eine umbenannte Property, ein neues Pflichtfeld im Request oder ein eingeschränktes Enum. Ein Diff in der Pipeline findet sie vor dem Release.

12. Deprecations markieren und jede Änderung auf Breaking Changes prüfen

Das Flag deprecated gibt es für Operationen, Parameter und Properties. Portale zeigen es an, und Generatoren übernehmen es in den Code, sodass Konsumenten die Deprecation in ihrer IDE bemerken. Die Description nennt, ab wann das Element entfällt und welches Element an seine Stelle tritt. Zur Laufzeit nennt der Header Deprecation aus RFC 9745 den Zeitpunkt der Deprecation, und der Header Sunset aus RFC 8594 nennt das Datum der Abschaltung.

yaml
paths:
  /orders/{orderId}/cancel:
    post:
      operationId: cancelOrder
      tags: [Orders]
      deprecated: true
      description: >-
        Deprecated since version 2.4.0 and scheduled for removal on
        2027-06-30. Use PATCH /orders/{orderId} with status cancelled.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '204':
          description: The order was cancelled.

Die Prüfung auf Breaking Changes übernimmt der Diff in der Pipeline. Er blockiert den Merge, wenn er einen Breaking Change findet und die Major-Version gleich geblieben ist. Das gilt auch für eine entfernte Operation. Sie wird deshalb zuerst als deprecated markiert und erst mit der nächsten Major-Version entfernt. Wie info.version mit diesen Änderungen zusammenhängt, beschreibt API-Versionierungsstrategie. In API Portal zeigt der Versionsvergleich die Unterschiede zwischen zwei API-Versionen nebeneinander.

Welche Regeln prüft ein Linter, und welche brauchen ein Review?

Linter und Spec-Diff decken fünf der zwölf Regeln nahezu vollständig ab und von den übrigen sieben den strukturellen Teil. Das sind die Regeln zu Operation IDs, Beispielen, Error Responses, Security und Breaking Changes. Alle diese Prüfungen laufen in der Pipeline mit und kosten nach der Einrichtung kaum noch Zeit.

Im Review bleiben die fachlichen Fragen, die kein Linter beantworten kann. Der Reviewer entscheidet, ob ein Name aus der Fachsprache kommt und ob eine Description einem Konsumenten hilft. Er beurteilt auch, ob die Grenzwerte eines Schemas fachlich stimmen und ob die Tag-Struktur zur Fachdomäne passt. Wie sich die Arbeit zwischen Linter und Review aufteilt, vertieft Manuelle Review vs. automatisches Linting. Welche Kategorien von Linter-Regeln es gibt und wie Schweregrade (Severity) ein Quality Gate steuern, beschreibt OpenAPI Linting.

Wer ist Owner des OpenAPI Style Guides?

Ein Style Guide braucht einen Owner, der das Regelwerk pflegt und über Ausnahmen entscheidet. Meist übernimmt das Plattform-Team oder die API-Governance diese Rolle. Teams beantragen eine Änderung oder Ausnahme per PR gegen das Regelwerk. So steht jede Entscheidung im selben Repository wie die Regeln und bleibt nachvollziehbar.

Neue Regeln starten am besten als Warning, damit Teams die Findings sehen, bevor ein Merge daran scheitert. Nach einigen Wochen werden sie für neue und geänderte Specs zum Error, während bestehende Specs eine Baseline bekommen und bei der nächsten Änderung nachgezogen werden. So wird keine ältere API über Nacht blockiert, und das Regelwerk gilt trotzdem für alles, was sich ändert. Wie der Style Guide in das übrige Governance-Modell passt, beschreibt Was ist API Governance?.

So starten Sie mit OpenAPI Best Practices

Der erste Schritt ist ein Lint-Lauf über alle bestehenden Specs als Baseline. Er zeigt, wo der Bestand steht und welche Findings am häufigsten vorkommen. Für den Anfang eignen sich dann die fünf Regeln, die sich vollständig automatisch prüfen lassen. Das sind eindeutige Operation IDs, gemeinsame Error Responses, Security je Operation, gültige Beispiele und die Prüfung auf Breaking Changes. Diese Regeln starten als Warning für neue und geänderte Specs und werden nach einigen Wochen zum Error, während das Regelwerk schrittweise weiterwächst.

API Linter
Den OpenAPI Style Guide in jedem PR durchsetzen
150+ Regeln ab Werk, parametrisierbar und um eigene Regeln erweiterbar, mit Findings direkt im Merge Request.
API Linter ansehen

Häufige Fragen zu OpenAPI Best Practices

Die Spezifikation heißt OpenAPI, seit sie an die OpenAPI Initiative übergegangen ist, und 3.0 war die erste Hauptversion unter diesem Namen. Swagger bezeichnet die Versionen bis 2.0 und die Tools, die SmartBear weiterhin unter diesem Namen veröffentlicht. Den Unterschied erklärt OpenAPI vs Swagger ausführlich.

Entscheidend ist, ob Generator, Gateway und Portal die Version unterstützen. Version 3.1 bringt volle Kompatibilität mit JSON Schema. Version 3.2 ergänzt hierarchische Tags, die QUERY-Methode und Streaming. Wenn die gesamte API-Toolchain 3.2 liest, können neue APIs dort starten. Andernfalls ist 3.1 das sicherere Ziel.

Weniger, als die meisten Teams anfangs aufschreiben. Wenige Regeln, die den Merge blockieren, bringen mehr als eine lange Liste von Warnings, die niemand liest. Teams starten in der Regel mit fünf bis zehn verbindlichen Regeln und nehmen weitere dazu, sobald die bestehenden Specs die ersten Regeln einhalten.

Ja. Eine Spec, die aus Annotationen generiert wird, landet bei denselben Generatoren, Gateways und Portalen wie eine von Hand geschriebene. Der einzige Unterschied liegt beim Beheben, denn Findings werden dann in den Annotationen im Code korrigiert. Ein Lint-Lauf über die generierte Spec in der Pipeline findet die Probleme in beiden Fällen, und Spec-First API-Entwicklung vergleicht die beiden Vorgehensweisen.