Swagger/OpenAPI-Generierung für TypeScript: Die besten Tools

Swagger/OpenAPI-Generierung für TypeScript: Vollständige Anleitung zu den Tools

\n\n

Die Entwicklung moderner Webanwendungen mit TypeScript ist untrennbar mit der Erstellung typsicherer API-Clients verbunden. Das manuelle Schreiben von Schnittstellen für jeden Endpunkt ist eine zeitaufwändige und fehleranfällige Aufgabe. Glücklicherweise gibt es einen leistungsstarken Ansatz – die automatische Generierung von TypeScript-Code aus OpenAPI (Swagger)-Spezifikationen. In diesem Artikel werden wir die besten Tools für diese Aufgabe, ihre Funktionen und Anwendungsbeispiele im Detail besprechen.

\n\n

Warum sollte man die Generierung aus OpenAPI nutzen?

\n

OpenAPI (früher Swagger) ist ein Standard zur Beschreibung von REST-APIs. Durch die Verwendung einer YAML- oder JSON-Spezifikationsdatei erhalten Sie:

\n

\n
• 100% Typisierung – TypeScript-Schnittstellen, die exakt dem Schema von Anfragen und Antworten entsprechen
\n
• Synchronisation mit dem Backend – bei API-Änderungen reicht eine Neugenerierung des Codes
\n
• Weniger Fehler – der TypeScript-Compiler erkennt Typinkonsistenzen bereits in der Entwicklungsphase
\n
• Autovervollständigung in der IDE – IntelliSense schlägt Felder und Typen vor
\n

\n\n

Top-Tools zur Generierung von TypeScript aus OpenAPI

\n\n

1. openapi-typescript-codegen (empfohlen)

\n

Dieses Tool hat aufgrund seiner Einfachheit und modernen Herangehensweise an Popularität gewonnen. Es generiert sauberen, gut strukturierten Code mit Unterstützung für axios oder fetch.

\n\n

Installation:

\n

npm install -D openapi-typescript-codegen

\n\n

Anwendungsbeispiel:

\n

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

\n\n

Generierter Code:

\n

// generated/models/User.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n    role: 'admin' | 'user';\n}\n\n// generated/services/UserService.ts\nexport class UserService {\n    public async getUsers(): Promise<User[]> {\n        return this.httpRequest.request({\n            method: 'GET',\n            url: '/users',\n        });\n    }\n}

\n\n

Vorteile:

\n

\n
• Unterstützung von OpenAPI 3.0 und 3.1
\n
• Generierung von Modellen, Services und Typen für Anfragen
\n
• Optionale Generierung von Hooks für React Query
\n
• Anpassbare Vorlagen über Handlebars
\n

\n\n

2. OpenAPI Generator (openapi-generator)

\n

Offizieller Generator der OpenAPI-Community. Unterstützt über 50 Sprachen, einschließlich TypeScript (mehrere Generatoren).

\n\n

Installation:

\n

npm install -D @openapitools/openapi-generator-cli

\n\n

Anwendungsbeispiel:

\n

npx openapi-generator-cli generate \\\n    -i spec.yaml \\\n    -g typescript-axios \\\n    -o ./generated

\n\n

Generierter Code:

\n

// generated/api.ts\nexport const UsersApiAxiosParamCreator = {\n    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {\n        const localVarPath = `/users`;\n        return {\n            url: localVarPath,\n            method: 'GET',\n        };\n    }\n}

\n\n

Besonderheiten:

\n

\n
• Generatoren: typescript-axios, typescript-fetch, typescript-angular
\n
• Unterstützung von Autorisierung (OAuth2, API Key)
\n
• Generierung von Dokumentation und Tests
\n
• Funktioniert über CLI oder Maven/Gradle-Plugins
\n

\n\n

3. swagger-typescript-api

\n

Leichter und schneller Generator, der auf sauberes TypeScript ohne überflüssige Abhängigkeiten ausgerichtet ist.

\n\n

Installation:

\n

npm install -D swagger-typescript-api

\n\n

Anwendungsbeispiel:

\n

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

\n\n

Generierter