⚙️Code & Werkzeuge

Aus der Beschreibung lässt sich Code erzeugen – hier nur zur Anzeige und bewusst klein gehalten, damit man das Prinzip sieht: Schemas werden zu Typen, Operationen zu Funktionen, Beispiele zu curl-Befehlen.

YAML (components.schemas.Book)
Book:
  description: Ein Buch im Katalog (NewBook plus Server-Felder)
  allOf:
    - $ref: "#/components/schemas/NewBook"
    - type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
TypeScript
export type Book = NewBook & {
  readonly id: number;
};
  • • required → Feld ohne ?, sonst optional
  • • type: [string, 'null'] → string | null
  • • enum → Union aus Literalen · allOf → & · oneOf/anyOf → |
  • • $ref → Name des Typs (Rekursion ist in TypeScript kein Problem)
  • • readOnly → readonly · format: int64 → number (Achtung: nur bis 2⁵³ exakt)

🧰Werkzeuge im Überblick

Eine Auswahl verbreiteter Open-Source-Werkzeuge. Befehle mit npx laden das Paket bei Bedarf aus npm.

openapi-generator

Generator

Clients und Server-Stubs für sehr viele Sprachen und Frameworks (Java-basiert, auch per npm-Wrapper).

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

openapi-typescript

Generator

Erzeugt nur TypeScript-Typen – ohne Laufzeitcode. Dazu passend: openapi-fetch als schlanker typisierter Client.

npx openapi-typescript openapi.yaml -o ./src/api/schema.d.ts

Orval

Generator

TypeScript-Clients (fetch, axios), Hooks für TanStack Query/SWR und Mock-Handler.

npx orval --input openapi.yaml --output ./src/api.ts

Prism

Mock-Server

Startet aus der Spezifikation einen Mock-Server mit den Beispielen; als Proxy prüft er echten Verkehr gegen die Spezifikation.

npx @stoplight/prism-cli mock openapi.yaml   # http://127.0.0.1:4010

Spectral

Linter

Regelbasierter Linter mit eingebautem OpenAPI-Regelsatz (spectral:oas) und eigenen Regeln im Team-Stil.

echo 'extends: ["spectral:oas"]' > .spectral.yaml
npx @stoplight/spectral-cli lint openapi.yaml

Redocly CLI

Linter / Bundler

Lint, Aufteilen und Zusammenfassen (bundle) mehrerer Dateien mit externen $ref, Doku-Vorschau.

npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

Swagger UI · Redoc · Scalar

Dokumentation

Rendern die Spezifikation als interaktive Referenz (Try it out, Codebeispiele).

# z. B. als statische Seite oder Middleware im Framework einbinden

Schemathesis

Tests

Property-based Testing: erzeugt aus den Schemas viele Anfragen und prüft die Antworten gegen die Spezifikation.

schemathesis run openapi.yaml --url https://api.example.org/v1

🔀Design-First oder Code-First?

📐 Design-First (API-First)

openapi.yaml  ──review──►  Freigabe
     │
     ├──► Mock-Server (Prism)  ──► Frontend startet
     ├──► Client-SDK (Generator)
     ├──► Server-Stub ──► Implementierung
     └──► Vertragstests in der CI
  • ✅ Vertrag steht vor dem Code, Teams arbeiten parallel
  • ✅ Review der API ohne Implementierungsdetails
  • ⚠️ Implementierung muss per Test/Validator an die Datei gebunden werden

💻 Code-First

Controller + Annotationen / Typen
     │   (z. B. FastAPI, NestJS, springdoc)
     ▼
openapi.json wird beim Build/Start erzeugt
     │
     └──► Doku, Clients …
  • ✅ Spezifikation kann nicht vom Code abweichen
  • ✅ Schneller Einstieg für bestehende Services
  • ⚠️ API-Design folgt oft der Implementierung statt den Nutzern
✅ Egal welcher Weg: die Datei gehört ins Repository
Versioniert neben dem Code, in der CI gelintet (Spectral/Redocly) und bei Änderungen auf Breaking Changes geprüft – dann bleibt der Vertrag verlässlich.