Wygeneruj gotowe typy TypeScript z OpenAPI
Masz spec OpenAPI dla swojego API i potrzebujesz typów TypeScript. Teraz. Bez przepisywania każdej ścieżki i kształtu ręcznie, bez pominięcia parametru, bez zapomnienia, że jedno pole z sekcji paths jest opcjonalne.
Wklejasz YAML albo JSON po lewej, dostajesz czysty typ `paths` (URL do metody, do kształtów żądania i odpowiedzi) plus typowane Schema components po prawej. Generator podąża za \$ref, przechodzi każdy operationId i emituje jeden samowystarczalny plik `.ts` który wrzucasz do projektu.
Trzy szybkie opcje: tylko komponenty schematu (pomija blok `paths` gdy chcesz tylko kształty danych), JSDoc z opisów (żeby IDE pokazywało dokumentację API po najechaniu kursorem) oraz prawdziwe deklaracje `enum` zamiast unii literałów stringa, jeśli wolisz ten styl.
Jak używać
- Wklej specyfikację OpenAPI po lewej. YAML albo JSON, wersja 3.0 albo 3.1. Domyślnie wgrywa się minimalny przykład Petstore, żebyś od razu zobaczył działający generator.
- Wybierz format: zostaw na Auto i tool sam wykryje YAML albo JSON po pierwszym znaku (`{` to JSON, wszystko inne to YAML). Wymuś jawnie, jeśli Twoja spec jest nietypowa.
- Włącz "Tylko komponenty schema" gdy chcesz tylko kształty danych (blok `components.schemas`) bez mapowania `paths`. Przydatne gdy piszesz własnego klienta HTTP ręcznie.
- Włącz "Dodaj JSDoc z opisów" żeby Twoje pola `description` i `title` zostały komentarzami JSDoc nad każdą wygenerowaną właściwością. IDE pokaże dokumentację API po najechaniu kursorem.
- Włącz "Użyj enum zamiast unii stringów" dla pól z `enum: [available, pending, sold]`. Z włączonym: `enum Status { available, pending, sold }`. Z wyłączonym: `"available" | "pending" | "sold"` (domyślnie, lepsze dla tree-shakingu).
- Kliknij `Kopiuj` żeby wrzucić wynik do schowka, albo `Pobierz` żeby zapisać jako plik `openapi.ts`. Wklejasz do projektu, importujesz typy `paths` i `components`, gotowe.
- Wyjście regeneruje się automatycznie podczas pisania (z półsekundową pauzą). Nie musisz klikać przycisku build.
Kiedy się przydaje
Pięć konkretnych sytuacji, w których to oszczędza godziny ręcznego przepisywania:
- Wchodzisz do istniejącego API. Backend opublikował spec OpenAPI. Wklejasz ją tutaj, dostajesz w kilka sekund typy każdego żądania i każdej odpowiedzi. Budujesz typowaną opakówkę nad `fetch` i IDE podpowiada każdy endpoint.
- Synchronizujesz typy z backendem. Spec to kontrakt. Uruchamiasz tool, kiedy backend wypuści nowy endpoint, wklejasz nowy `openapi.ts` do projektu, kompilator TypeScript wskazuje każde miejsce, które wymaga aktualizacji.
- Generujesz typowane SDK dla publicznego API. Stripe, GitHub, Linear i większość nowoczesnych dostawców SaaS publikuje spec OpenAPI. Wrzucasz ją tutaj i masz typowanego klienta w minutę, bez `any` w żadnym miejscu.
- Piszesz fixture do testu z prawdziwego kształtu. Potrzebujesz mocka `Pet` do testu. Generujesz typy, najedziesz w edytorze na typ, IDE pokazuje każde wymagane pole. Koniec zgadywania, co naprawdę zwraca API.
- Migrujesz ze Swagger 2.0 / OpenAPI 3.0 na 3.1. Obie wersje są wspierane. Wklejasz starą spec, regenerujesz, porównujesz diff: od razu widzisz, które pola zyskały semantykę `nullable` albo trafiły do oznakowanej unii.
Do testowania samych endpointów po wygenerowaniu typów najlepszy jest tester zapytań HTTP, a w trakcie pracy nad frontem realny backend może zastąpić generator mock API. Dla GraphQL użyj konwertera GraphQL → TS, dla luźnego JSON-a bez specyfikacji konwertera JSON → TS.