openapi-typescript für TypeScript: Komplettleitfaden mit Beispielen

In der modernen Webentwicklung spielen APIs eine zentrale Rolle, und die Spezifikation mit dem OpenAPI-Standard (ehemals Swagger) hat sich zum De-facto-Standard entwickelt. Die manuelle Pflege von TypeScript-Typen, die mit der OpenAPI-Spezifikation übereinstimmen, ist jedoch zeitaufwendig und fehleranfällig. Die Bibliothek openapi-typescript löst dieses Problem, indem sie automatisch strenge TypeScript-Typen auf Basis Ihres OpenAPI-Schemas (v3.0 und v3.1) generiert.

Das Hauptziel der Bibliothek ist es, eine type-safe Interaktion mit der API zu gewährleisten. Anstatt manuell Schnittstellen für jeden Endpunkt zu deklarieren, führen Sie den Generator aus, der eine einheitliche Datei (oder mehrere) mit Typen für alle Anfragen, Antworten, Parameter und Schemas erstellt. Das spart nicht nur Zeit, sondern stellt auch sicher, dass Ihre Typen immer mit der aktuellen API-Version synchronisiert sind. Ändert sich die Spezifikation, genügt es, die Typen neu zu generieren, und der TypeScript-Compiler zeigt sofort alle Unstimmigkeiten im Code an.

Die Bibliothek wird aktiv in Projekten eingesetzt, bei denen Zuverlässigkeit und Entwicklungsgeschwindigkeit entscheidend sind – von Microservice-Architekturen bis hin zu SPA-Anwendungen. Sie unterstützt die Generierung sowohl für die Client-Seite (z. B. für fetch oder axios) als auch für die Server-Seite (z. B. für Express oder Fastify). In diesem Artikel gehen wir detailliert auf die Installation, die wichtigsten Methoden, praktische Beispiele und typische Fehler ein.

Installation

Verwenden Sie npm oder yarn, um die Bibliothek zu installieren. Der Befehl installiert sowohl den Generator selbst als auch die erforderlichen Abhängigkeiten.

npm install openapi-typescript typescript @types/node --save-dev

Oder mit yarn:

yarn add -D openapi-typescript typescript @types/node

Wenn Sie die generierten Typen zur Laufzeit verwenden möchten (z. B. für die Validierung), installieren Sie zusätzlich openapi-typescript-helpers:

npm install openapi-typescript-helpers

Schnellstart – Minimales Arbeitsbeispiel

Angenommen, Sie haben eine Datei spec.yaml mit einer OpenAPI-Spezifikation. Erstellen wir ein einfaches Skript zur Generierung der Typen.

// generate.ts
import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

async function main() {
  const spec = fs.readFileSync('./spec.yaml', 'utf-8');
  const result = await createClient(spec, { format: 'yaml' });
  fs.writeFileSync('./api-types.d.ts', result);
  console.log('Typen wurden in api-types.d.ts generiert');
}

main().catch(console.error);

Führen Sie das Skript aus:

npx ts-node generate.ts

Danach erscheinen in der Datei api-types.d.ts alle Typen, die Ihrer Spezifikation entsprechen. Sie können diese nun in Ihrem Projekt importieren:

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

// Verwendung des Typs für einen bestimmten Endpunkt
type GetUsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Wichtige Methoden und Funktionen

1. createClient(schema: string, options?: ClientOptions): Promise<string>

Funktion: Die Hauptmethode zur Generierung von Typen. Sie nimmt einen String mit der Spezifikation (JSON oder YAML) entgegen und gibt einen String mit TypeScript-Code zurück.

import { createClient } from 'openapi-typescript';
import * as fs from 'fs';

const spec = fs.readFileSync('./spec.json', 'utf-8');
const types = await createClient(spec, { format: 'json' });
fs.writeFileSync('./types.d.ts', types);

2. createClientFromUrl(url: string, options?: ClientOptions): Promise<string>

Funktion: Lädt die Spezifikation asynchron von einer URL herunter und generiert die Typen. Nützlich für entfernte APIs.

                
    

  
Auch in der Bibliothek
  

                
                  
                 PDF-Berichterstellung mit C# (.NET) mit iTextSharp und QuestPDF
      
                
                  
                 migrate für Go: Vollständige Anleitung mit Beispielen
      
                
                  
                 Maschinelles Lernen mit Java: Überblick über die wichtigsten Bibliotheken
      
                
                  
                 Arbeiten mit Bildern in Java: Vom Lesen bis zur Verarbeitung
      
                
                  
                 JWT-Tokens in Kotlin: Vollständiger Leitfaden mit Codebeispielen