Swagger/OpenAPI-Generierung für TypeScript: Bibliotheken und Werkzeuge

Swagger/OpenAPI-Generierung für TypeScript: Automatisierung der Erstellung von API-Clients

Bei der Entwicklung moderner Webanwendungen in TypeScript stellt sich oft die Aufgabe der Integration mit einer REST-API, die über OpenAPI-Spezifikationen (früher bekannt als Swagger) beschrieben wird. Das manuelle Schreiben von Typen, Schnittstellen und Client-Code ist nicht nur zeitaufwändig, sondern auch fehleranfällig, insbesondere bei Änderungen am Backend. Hier helfen Werkzeuge zur automatischen Generierung von TypeScript-Code aus OpenAPI-Spezifikationen. In diesem Artikel betrachten wir drei der beliebtesten Lösungen: openapi-typescript, orval und swagger-typescript-api, und vergleichen ihre Funktionen.

Warum ist die Generierung von TypeScript aus OpenAPI notwendig?

Das Hauptziel ist die Synchronisation von Typen und Client-Code zwischen Frontend und Backend. Vorteile der automatischen Generierung:

• Typsicherheit: Alle Endpunkte, Anfrageparameter und Antworten erhalten strenge TypeScript-Typen.
• Aktualität: Bei Änderungen an der Spezifikation reicht es aus, den Code neu zu generieren, ohne manuelle Anpassungen vorzunehmen.
• Entwicklungsbeschleunigung: Der Entwickler erhält fertige Funktionen zum Aufrufen der API mit Autovervollständigung (IntelliSense).
• Fehlerminimierung: Tippfehler in Feldnamen und Typinkonsistenzen werden vermieden.

openapi-typescript

Die Bibliothek openapi-typescript (von den Entwicklern von openapi-fetch) ist ein leichtgewichtiger Typengenerator. Sie erstellt nur TypeScript-Schnittstellen und -Typen, ohne Client-Code für API-Aufrufe zu generieren. Dies ist die ideale Wahl für Projekte, in denen Daten streng typisiert werden müssen, die Art des API-Aufrufs jedoch dem Entwickler überlassen bleibt (z. B. über fetch oder axios).

Installation:

npm install -D openapi-typescript

Beispielverwendung (Generieren von Typen aus der Datei spec.yaml):

npx openapi-typescript ./spec.yaml -o ./types/api.ts

Das Ergebnis ist eine Datei mit Typen, die importiert werden können:

import type { paths } from './types/api';

// Typ für die Antwort von GET /userstype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Vorteile: Minimalismus, schnelle Generierung, hervorragende Unterstützung komplexer Schemata (allOf, oneOf).
Nachteile: Keine fertigen Funktionen für API-Aufrufe, zusätzlicher Wrapper erforderlich.

orval

Orval ist ein leistungsstarker Generator, der nicht nur Typen, sondern auch voll funktionsfähige React-Hooks sowie Clients für axios, fetch oder Angular erstellt. Er ist besonders nützlich in React-Projekten, die React Query (TanStack Query) verwenden.

Installation:

npm install -D orval

Konfiguration in der Datei orval.config.ts:

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // oder 'axios', 'fetch', 'angular'    },  },};

Starten der Generierung:

npx orval

Beispiel eines generierten Hooks:

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // data wird automatisch typisiert}

Vorteile: Fertige Integration mit React Query, Unterstützung von Mutationen, automatische Cache-Verwaltung.
Nachteile: Großer Umfang des generierten Codes, Bindung an einen bestimmten HTTP-Client.

swagger-typescript-api

Die Bibliothek swagger-typescript-api bietet flexible Generierung: Es können sowohl einfache Typen als auch ein vollwertiger API-Client mit Unterstützung verschiedener HTTP-Clients (axios, fetch) erstellt werden. Eine besondere Eigenschaft ist die Möglichkeit zur Anpassung der Generierungsvorlagen.

Installation: