Generator OpenAPI

Generator OpenAPI: specyfikacja API w YAML lub JSON

Generator OpenAPI zamienia listę endpointów w plik specyfikacji OpenAPI 3.0.3, który można pobrać jako openapi.yaml albo openapi.json. OpenAPI to standard opisu API REST: na jego podstawie powstaje dokumentacja (Swagger UI, Swagger Editor), kolekcje w Postmanie, klienci SDK i testy kontraktowe.

Struktura specyfikacji

Format endpointów

Każdy endpoint to osobny wiersz METODA; ścieżka; opis, np. GET; /users; Lista użytkowników. Zamiast średnika można użyć pionowej kreski |. Obsługiwane metody to GET, POST, PUT, PATCH, DELETE, HEAD i OPTIONS, a wielkość liter nie ma znaczenia. Ścieżka musi zaczynać się od /, a każdy fragment w klamrach, np. {id}, staje się parametrem path. Jeden plik mieści do 100 endpointów.

Nie musisz wpisywać wszystkiego ręcznie. Gotowe zestawy (CRUD użytkowników, sklep, blog) wczytują przykładowe API, a pole „Dopisz komplet CRUD” dodaje dla podanego zasobu pięć endpointów: GET i POST /zasób oraz GET, PUT i DELETE /zasób/{id}, z pominięciem tych, które już są na liście.

Autoryzacja

• Bearer – token JWT w nagłówku Authorization (schemat bearerAuth).
• Klucz API – klucz w nagłówku X-API-Key (schemat apiKeyAuth). Inną nazwę nagłówka trzeba poprawić w pliku ręcznie.
• Brak – plik nie zawiera sekcji security ani components.

Jak generator zamienia listę endpointów na specyfikację OpenAPI

Generator czyta tekst wiersz po wierszu i dzieli każdy na trzy części: metodę, ścieżkę i opis. Metoda jest sprawdzana względem listy obsługiwanych, a ścieżka trafia jako klucz do sekcji paths, z metodą jako zagnieżdżonym kluczem operacji. Opis staje się polem summary; jeśli go brak, generator wpisze np. „Get /users”. Błędny wiersz (nieznana metoda, ścieżka bez ukośnika, niedomknięta klamra, powtórzony endpoint) zatrzymuje generowanie i komunikat wskazuje jego numer.

Parametry path wykrywane są przez nawiasy klamrowe. Dla segmentu {id} generator tworzy wpis parameters z polami name: id, in: path, required: true i typem string. Tak samo działa każda inna nazwa w klamrach, także kilka parametrów w jednej ścieżce. Każda operacja dostaje odpowiedzi 200 i 400, a POST dodatkowo 201.

Cztery dodatki są opcjonalne. operationId powstaje z metody i ścieżki (GET /users/{id} → getUsersById) i jest unikalne w pliku, co pozwala generatorom SDK tworzyć czytelne nazwy funkcji. Tagi grupują operacje według pierwszego segmentu ścieżki, z pominięciem „api” i wersji typu v1. Szkielet JSON dodaje requestBody dla POST, PUT i PATCH oraz content application/json w odpowiedziach. Ostatnia opcja dopisuje 401 (gdy jest autoryzacja) i 404 (dla ścieżek z parametrem). W YAML wcięcie ma zawsze 2 spacje, a wartości, które parser odczytałby jako liczbę lub wartość logiczną (np. wersja 1.0, yes), trafiają do pliku w cudzysłowie.

Przykład krok po kroku: API sklepu z trzema endpointami

1. W polu tytuł wpisujesz Sklep API, w polu wersja 1.0.0, a jako serwer podajesz https://api.sklep.pl.
2. Wybierasz autoryzację Bearer – generator doda schemat http/bearer z formatem JWT.
3. W polu endpointów wklejasz trzy wiersze: GET; /products; Lista produktów, GET; /products/{id}; Szczegóły produktu, POST; /orders; Nowe zamówienie.
4. Generator tworzy trzy ścieżki i trzy operacje. Kafelki nad wynikiem pokażą: Ścieżki 3, Operacje 3.
5. Ze ścieżki /products/{id} powstaje jeden parametr path o nazwie id, required: true, typ string. Pozostałe ścieżki nie mają parametrów.
6. Obie operacje GET mają odpowiedzi 200 i 400, a POST /orders – 200, 201 i 400. Po zaznaczeniu operationId nazwy to getProducts, getProductsById i postOrders; po zaznaczeniu odpowiedzi 401 i 404 każda operacja dostanie 401, a 404 tylko GET /products/{id}.

Gdy dwie operacje mają tę samą ścieżkę (np. GET i PUT /products/{id}), liczba ścieżek będzie mniejsza od liczby operacji.

Mapowanie pól formularza na elementy specyfikacji

Praktyczne wskazówki przy generowaniu specyfikacji

• Jedna metoda na wiersz. Zapis w rodzaju „GET, POST” generator odrzuci jako nieznaną metodę, więc dla endpointu z kilkoma metodami wpisz kilka wierszy z tą samą ścieżką.
• Generator bierze pod uwagę tylko dwa pierwsze separatory. Średnik lub kreska w dalszej części wiersza zostają w opisie jako zwykły tekst.
• Parametry w klamrach pisz literami łacińskimi, cyframi i podkreślnikiem: {id}, {slug}, {orderId}. Każdy dostaje typ string; po wygenerowaniu możesz zmienić go na integer lub dodać format, np. uuid.
• Wygenerowany plik to szkielet. Schemat type: object ze szkieletu JSON uzupełnij o properties i required, najlepiej w components.schemas, aby Swagger UI pokazywał modele, a generator klientów tworzył typy.
• Przy ręcznej edycji YAML pamiętaj, że nie toleruje on tabulatorów. Używaj spacji i spójnego wcięcia, inaczej walidator zgłosi błąd.

Czego narzędzie nie uwzględnia

• Modeli danych. Generator nie tworzy components.schemas ani przykładów ciał żądań; szkielet JSON wstawia tylko ogólny schemat type: object.
• Parametrów innych niż path. Parametry query, nagłówkowe (poza autoryzacją) i cookie trzeba dopisać ręcznie, np. dla filtrowania i paginacji.
• Wielu środowisk i mieszanej autoryzacji. Formularz przewiduje jeden adres serwera i jeden schemat security dla całego API.
• Zgodności z działającym API. Generator nie sprawdza, czy endpointy odpowiadają pod podanym adresem: specyfikacja opisuje to, co wpiszesz.