Generator klienta OpenAPI

Generator klienta OpenAPI

Zamiast pisać ręcznie metody API, wygeneruj spójny klient oparty na natywnym fetch. Każdy endpoint staje się metodą z poprawnymi parametrami. Generator klienta OpenAPI przyjmuje prostą listę endpointów albo dokument OpenAPI w formacie JSON i zwraca jeden plik api-client.ts lub api-client.js bez zewnętrznych zależności.

Format endpointów

GET /users | getUsers
POST /users | createUser
GET /users/{id} | getUser

Jeden endpoint na linię: metoda HTTP, ścieżka i nazwa metody po znaku |. Obsługiwane metody to GET, POST, PUT, PATCH i DELETE. Parametry ścieżki w nawiasach klamrowych stają się argumentami metody. Metody POST/PUT/PATCH przyjmują dodatkowo body. Nazwę można pominąć: wtedy powstaje z metody i ścieżki, np. GET /users/{id} daje getUsersById. Linie puste oraz zaczynające się od # lub // są pomijane, a jedna lista może mieć do 200 endpointów.

Co generuje

• stałą BASE_URL z podanym adresem bazowym (końcowy ukośnik jest usuwany),
• funkcję bazową request(), która ustawia nagłówki, zamienia body na JSON i rzuca wyjątek przy statusie spoza 2xx,
• mechanizm autoryzacji: setToken() dla Bearer albo setApiKey() dla nagłówka X-API-Key; można też wybrać brak autoryzacji,
• obiekt klienta z metodami per endpoint, nazwany tak, jak wpiszesz w polu „Nazwa klienta”,
• opcjonalnie klasę ApiError z polem status i parametr typu odpowiedzi <T> w każdej metodzie.

Pod kodem narzędzie pokazuje tabelę metod (metoda, ścieżka, sygnatura funkcji) i gotowy przykład użycia z importem. Klient powstaje w TypeScript albo w czystym JavaScript.

Przykład

Dla trzech linii z sekcji powyżej, w TypeScript z typami pomocniczymi, metody obiektu ApiClient wyglądają tak:

getUsers<T = unknown>() { return request<T>("GET", `/users`); },
createUser<T = unknown>(body: unknown) { return request<T>("POST", `/users`, body); },
getUser<T = unknown>(id: string | number) { return request<T>("GET", `/users/${encodeURIComponent(String(id))}`); },

Wywołanie await ApiClient.getUser<User>(42) wysyła GET na https://api.example.com/users/42 i zwraca odpowiedź jako User. Parametr jest kodowany przez encodeURIComponent, więc getUser("a/b") trafi pod /users/a%2Fb, a nie do innej ścieżki.

Jak działa generator klienta API w TypeScript

Narzędzie przyjmuje listę endpointów w prostym formacie. Każdy wiersz opisuje metodę HTTP, ścieżkę oraz nazwę metody w kliencie. Pełna specyfikacja OpenAPI nie jest potrzebna. Generator pracuje na tym, co wpiszesz, więc wynik jest przewidywalny i łatwy do skorygowania, a listę łatwo przygotować z arkusza albo dokumentacji. Linie, których nie da się odczytać (np. z metodą HEAD albo spacją w ścieżce), są pomijane, a w uwagach widać numer linii i powód.

Jeśli w ścieżce pojawi się {id}, generator tworzy argument id i podstawia go do template stringa. Nazwy z łącznikami zamienia na camelCase ({user-id} daje userId), a słowa zastrzeżone w JavaScript dostają przyrostek Param ({class} daje classParam). W metodach GET i DELETE argumenty trafiają tylko do adresu, a w POST, PUT i PATCH dodatkowo pojawia się body. Dzięki temu metoda createUser może przyjąć dane nowego użytkownika, a getUser tylko identyfikator. Jeśli ścieżka ma kilka nawiasów, kolejność argumentów odpowiada kolejności ich wystąpienia: GET /users/{userId}/orders/{orderId} daje metodę z argumentami (userId, orderId). Powtórzona nazwa metody dostaje numer, np. getUser2.

Wspólna funkcja request() zawsze wysyła nagłówek Accept: application/json, a Content-Type: application/json tylko wtedy, gdy przekazujesz body. Odpowiedź 204 zwraca undefined, pozostałe odpowiedzi 2xx są parsowane jako JSON. W praktyce dostajesz cienką warstwę pośrednią, którą możesz rozwijać: dodać logowanie, ponawianie żądań albo własny parser odpowiedzi. Klient nie narzuca frameworka: zadziała w aplikacji frontendowej i w skrypcie Node.js.

Import endpointów z pliku OpenAPI JSON

Jeśli masz dokument OpenAPI, rozwiń panel „Mam plik OpenAPI (JSON)” i wklej go w całości. Generator czyta sekcję paths i z każdej operacji GET, POST, PUT, PATCH lub DELETE robi jedną linię endpointu. Nazwą metody zostaje operationId w camelCase, a gdy go brak, nazwa powstaje ze ścieżki. Pierwszy adres z servers trafia do pola „Bazowy URL”, o ile nie zawiera zmiennych typu {region}. Z components.securitySchemes rozpoznawany jest schemat http z bearer albo apiKey i na tej podstawie ustawiana jest autoryzacja. Dokument może mieć do 300 000 znaków i 200 operacji. Plik YAML trzeba najpierw zamienić na JSON, a schematy danych (components.schemas) nie są przenoszone, więc typy odpowiedzi podajesz sam.

Przykład krok po kroku: trzy endpointy

1. Wejście: wpisujesz trzy linie: GET /users | getUsers, POST /users | createUser oraz GET /users/{id} | getUser.
2. Liczba endpointów: 3 osobne definicje dają 3 metody w obiekcie klienta i wartość 3 w kafelku „Endpointów”.
3. Parametry ścieżki: tylko trzecia linia zawiera {id}, więc powstaje getUser(id: string | number), a kafelek „Z parametrami ścieżki” pokaże 1.
4. Body: tylko POST przyjmuje body, więc powstaje createUser(body), a kafelek „Z ciałem żądania” pokaże 1.
5. Szkielet: przy autoryzacji Bearer generator dokłada funkcje request() i setToken(). Razem z 3 metodami daje to 5 funkcji: request(), setToken(), getUsers(), createUser(), getUser(). Włączone typy pomocnicze dodają klasę ApiError, ale nie zmieniają liczby metod.
6. Wynik: wywołanie getUsers() trafia do GET /users, createUser(body) do POST /users, a getUser(id) do GET /users/{id}. Po jednym wywołaniu setToken("…") funkcja request() dokłada nagłówek Authorization: Bearer … do każdego żądania.

Tabela referencyjna: co generator zamienia na co

Praktyczne wskazówki przed generowaniem

• Ustal konwencję nazw metod. Nazwy w prawej kolumnie są przepisywane do obiektu klienta, więc getUsers, createUser i getUser powinny być spójne. Dzięki temu autouzupełnianie w edytorze podpowiada metody przewidywalnie, a ty nie mieszasz czasowników i liczby mnogiej.
• Pilnuj nawiasów klamrowych. Tylko fragment w nawiasach staje się argumentem: bez {id} metoda dostanie stałą ścieżkę i nie przyjmie identyfikatora.
• Pamiętaj o metodach z body. POST, PUT i PATCH dostają dodatkowy argument body, GET i DELETE nie. Jeśli Twoje API przyjmuje body w DELETE, dopisz argument ręcznie w wygenerowanej metodzie.
• Autoryzację wybierz świadomie. Bearer sprawdzi się przy tokenach dostępu, a klucz API przy prostych kluczach. Nazwa nagłówka klucza to zawsze X-API-Key; jeśli Twoje API oczekuje innej, zmień ją w request(). Token jest trzymany tylko w pamięci modułu, więc po przeładowaniu strony trzeba ponownie wywołać setToken().
• Przetestuj wynik w swoim środowisku. W Node 18+ fetch jest dostępny natywnie. W starszych wersjach potrzebny jest polyfill, inaczej wywołania zakończą się błędem. W przeglądarce serwer API musi zezwalać na Twoją domenę w nagłówkach CORS.

Ograniczenia i czynniki, które zaburzają wynik

• Brak pełnej specyfikacji OpenAPI. Import z JSON bierze tylko ścieżki, metody, operationId, adres serwera i rodzaj autoryzacji. Schematy, reguły walidacji oraz parametry i nagłówki opisane w specyfikacji są pomijane. Dla dużych API lepszym wyborem jest openapi-generator. To narzędzie tworzy szkielet, a nie pełny SDK.
• Parametry zapytania wpisujesz w ścieżce. Narzędzie nie buduje obiektu query params. Stałe wartości zapisz wprost (/users?sort=name), a zmienne jako placeholdery (/users?page={page}&limit={limit}), które staną się argumentami. Parametrów opcjonalnych, które czasem trzeba pominąć, ten zapis nie obsłuży; wtedy rozszerz request().
• Brak logiki biznesowej i retry. Wygenerowany klient nie obsłuży odświeżania tokenu, ponawiania żądań, limitów szybkości ani paginacji. To warstwa, którą trzeba dopisać osobno.
• Złożone formaty body i odpowiedzi wymagają korekty. request() zawsze wysyła JSON.stringify(body) i czyta odpowiedź przez res.json(). Przy FormData, wysyłaniu plików, odpowiedziach tekstowych lub binarnych (CSV, PDF) albo statusie 200 z pustym ciałem trzeba poprawić request() i sygnatury metod.