Generator kolekcji Postman

Generator kolekcji Postman

Generator kolekcji Postman zamienia listę endpointów w plik JSON w formacie Postman Collection v2.1, gotowy do importu. Kolekcja grupuje zapytania do API, umożliwia pracę zespołową i automatyczne testy, a import gotowego pliku oszczędza ręczne zakładanie każdego requestu. Razem z kolekcją pobierasz plik środowiska ze zmiennymi baseUrl oraz token lub apiKey.

Format endpointów

Każdy wpis to METODA; ścieżka; opis, np. GET; /users; Lista użytkowników. Zamiast średnika możesz użyć | albo samych spacji (GET /users Lista użytkowników). Generator tworzy osobne zapytanie dla każdego niepustego wiersza, najwyżej 100 w jednej kolekcji. Dozwolone metody to GET, POST, PUT, PATCH, DELETE, HEAD i OPTIONS.

Ścieżka musi zaczynać się od /, a adres serwera wpisujesz osobno w polu Base URL, np. https://api.example.com/v1 (tylko http lub https, bez loginu, hasła i parametrów). Na start możesz wczytać jeden z trzech szablonów: CRUD użytkowników, logowanie z odświeżaniem tokenu albo sklep z podziałem na foldery.

Zmienne i sekrety

Autoryzację ustawia się raz, na poziomie całej kolekcji, a każde żądanie ją dziedziczy. Wartości tokenu i klucza wpisz w środowisku Postmana, nie w samej kolekcji, aby nie wyciekły do repozytorium. Pobrany plik środowiska ma te pola puste i oznaczone typem secret.

Testy

Do każdego zapytania generator dodaje skrypt pm.test sprawdzający kod odpowiedzi. Domyślnie oczekiwany jest status 200, ale możesz wpisać dowolny od 100 do 599, np. 201. Druga opcja dokłada test czasu odpowiedzi poniżej 2000 ms. To podstawa automatyzacji testów API w Collection Runnerze i w CI.

Jak generator zamienia listę endpointów na kolekcję JSON v2.1

Generator działa jak parser prostego tekstu, a nie jak klient API: nie wysyła niczego do Twojego serwera. Każdy niepusty wiersz traktuje jako jeden wpis i dzieli go na najwyżej trzy części. Pierwsza staje się metodą (małe litery są zamieniane na wielkie), druga ścieżką, a cała reszta opisem. Jeśli którykolwiek wiersz jest błędny, kolekcja nie powstaje, a komunikat podaje numer wiersza i przyczynę.

Na tej podstawie budowany jest obiekt kolekcji w formacie Postman Collection v2.1. Generator tworzy tablicę item, a w niej osobny element dla każdego wpisu. Metoda trafia do pola request.method, adres do request.url, a opis staje się nazwą żądania na liście w Postmanie (bez opisu nazwą będzie np. „GET /users”). Jeśli w ścieżce występuje {parametr}, generator zamienia go na zmienną ścieżki :parametr z wartością 1, dzięki czemu ten sam request można uruchamiać dla różnych identyfikatorów. Parametry po znaku ? trafiają do listy Query Params.

Zmienne typu {{token}} i {{apiKey}} nie są rozwijane do wartości. Pozostają w pliku jako odwołania do środowiska Postmana. To zasada bezpieczeństwa: kolekcja może trafić do repozytorium, a sekrety ustawiasz poza nią. Każde żądanie dostaje nagłówek Accept: application/json, a POST, PUT i PATCH przy włączonej opcji „Body JSON” także Content-Type: application/json i przykładowe body {"example": "value"}.

Przykład: trzy endpointy, trzy zapytania, jedna zmienna ścieżki

1. Przygotuj trzy linie. Pierwsza: GET; /users; Lista użytkowników. Druga: POST; /users; Dodanie użytkownika. Trzecia: GET; /users/{id}; Szczegóły użytkownika.
2. Wklej tekst do generatora. Parser dzieli każdą linię na trzy segmenty: metodę, ścieżkę i opis. Base URL zostaw jako https://api.example.com, a autoryzację jako Bearer Token.
3. Sprawdź pierwszy wynik. Powstaje żądanie GET na {{baseUrl}}/users o nazwie Lista użytkowników.
4. Sprawdź drugi wynik. Powstaje żądanie POST na {{baseUrl}}/users z nagłówkiem Content-Type i przykładowym body JSON, które zastępujesz prawdziwymi polami.
5. Sprawdź trzeci wynik. Ścieżka /users/{id} zamienia się na {{baseUrl}}/users/:id, a zmienna id dostaje wartość 1 w zakładce Params.
6. Policz wynik. 3 wpisy = 3 itemy = 3 zapytania. Zmienne kolekcji: 2 (baseUrl i token). Z testem statusu kolekcja ma 3 testy, a po dodaniu testu czasu odpowiedzi 6.

Mapowanie danych wejściowych na elementy kolekcji

Praktyczne wskazówki przed generowaniem

• Jeden endpoint na linię. Nie łącz kilku metod w jednym wierszu, bo generator potraktuje go jako jeden wpis. Rozdzielenie liniami daje przewidywalną liczbę zapytań.
• Nie mieszaj separatorów. Wiersz GET /users; Lista zawiera średnik, więc jest dzielony tylko po średnikach i metodą staje się „GET /users”. Skończy się to błędem nieznanej metody.
• Opis pisz jak nazwę żądania. Krótkie Lista użytkowników, Dodanie użytkownika, Szczegóły zamówienia czyta się lepiej na liście w Postmanie i w raporcie z Collection Runnera.
• Parametry ścieżki zapisuj w nawiasach klamrowych. {id}, {orderId} i podobne oznaczenia zamienią się na zmienne :id, :orderId. Zapis :id też działa, a podwójne klamry Postmana, np. {{wersja}}, zostają bez zmian.
• Włącz foldery przy większym API. Opcja grupuje żądania według pierwszego segmentu ścieżki: /products i /products/{id} trafią do folderu products, a /orders do folderu orders.
• Sekrety trzymaj w środowisku. W kolekcji zostają tylko {{token}} i {{apiKey}}, a wartości wpisujesz w Postmanie. Nie commituj pliku środowiska z prawdziwymi kluczami.

Ograniczenia i czynniki zaburzające wynik

• Brak walidacji API. Generator sprawdza tylko format: metodę z listy, ukośnik na początku ścieżki, brak spacji i długość do 300 znaków. Nie wie, czy endpoint istnieje, więc literówka przejdzie do kolekcji jako poprawny JSON.
• Body to tylko szablon. Przykładowe {"example": "value"} trzeba zastąpić prawdziwymi polami. Inne nagłówki, przykładowe odpowiedzi i skrypty pre-request dodajesz ręcznie w Postmanie.
• Jeden oczekiwany status dla wszystkich żądań. Jeśli POST zwraca 201, a GET 200, test statusu w części żądań nie przejdzie. Popraw go po imporcie albo wygeneruj osobne kolekcje.
• Separatory w treści wiersza. Średniki w opisie zostają w nazwie żądania, bo wiersz jest dzielony najwyżej na trzy części. Znak | zawsze działa jak separator, więc nie używaj go w ścieżce.
• Nie zastępuje środowiska. Referencje {{token}} i {{apiKey}} pozostają tekstem. Bez wybranego i uzupełnionego środowiska Postman wyśle żądania bez poprawnego tokenu, a API odpowie zwykle kodem 401.