IT Systems Integration Consultant
Swagger pre testerov: Návod na testovanie REST API
Swagger je open-source framework na návrh, dokumentáciu a testovanie REST API. Pre QA tímy je to najrýchlejšia cesta, ako pochopiť, čo API ponúka, a hneď si overiť, či funguje podľa špecifikácie. Tri nástroje Swagger ekosystému (Swagger UI, Editor a Codegen) pokrývajú cestu od návrhu dokumentácie až po test konkrétneho endpointu v prehliadači.
V článku sa dozvieš:
Swagger otvoríš v prehliadači a do dvoch minút vieš, čo všetko API dokáže. Otvoríš nový projekt a prvá vec, ktorú hľadáš, je Swagger URL. Ak ho projekt nemá, máš problém: žiadnu spoľahlivú API dokumentáciu. Ak ho má, máš výhodu, kompletný prehľad endpointov a možnosť ich okamžite testovať priamo z prehliadača.
Presnejšie povedané, ide o open-source framework (vývojový rámec) pre celý životný cyklus REST API (aplikačného programovacieho rozhrania), od návrhu cez dokumentáciu až po testovanie. Poskytuje prehľadnú API dokumentáciu, ktorá pomáha vývojárom aj testerom pochopiť, ako aplikačné rozhranie funguje. Pre QA tímy je užitočné najmä interaktívne rozhranie, kde sa dá priamo poslať požiadavka a sledovať odpoveď servera. Vďaka tomu je jednoduchšie testovať endpointy a overovať správanie API rozhrania.
Čo je Swagger a na čo slúži
Ak sa pýtaš, čo je API (aplikačné programovacie rozhranie), ide o spôsob, akým spolu komunikujú rôzne softvérové systémy. API rozhranie funguje ako sprostredkovateľ medzi systémami: prijíma požiadavky od klienta a vracia odpovede zo servera. Najrozšírenejším typom je REST API, ktoré komunikuje prostredníctvom protokolu HTTP. Umožňuje klientovi požadovať dáta alebo vykonávať zmeny v systéme pomocou štandardných HTTP operácií.
REST API je typ API, ktoré dodržiava sadu architektonických pravidiel (REST = Representational State Transfer) a využíva štandardné HTTP metódy ako GET, POST, PUT a DELETE. S REST API dnes pracujú takmer všetky moderné webové a mobilné aplikácie.
Ako vzniklo Swagger API a čo dnes pokrýva?
Swagger vznikol v roku 2010 ako nástroj pre vývojárov, ktorí potrebovali jednoduchý spôsob, ako dokumentovať a zdieľať svoje API. Dnes sa s ním často stretneš pod pojmom Swagger API, ktorý označuje nástroje aj samotný prístup k práci s API dokumentáciou. Pred jeho príchodom sa dokumentácia API väčšinou písala ručne vo Worde a už pri prvej zmene kódu bola zastaraná. Ten problém rieši tak, že popis API sa generuje priamo z kódu alebo zo štandardizovaného súboru, takže zostáva vždy aktuálny.
Dnes Swagger poznáme ako sadu nástrojov (Swagger UI, Swagger Editor, Swagger Codegen), ktoré pomáhajú pri celom životnom cykle API, od návrhu, cez dokumentáciu, až po testovanie a generovanie kódu.
Okrem týchto open-source nástrojov existuje aj platforma SwaggerHub, cloudové riešenie od spoločnosti SmartBear, ktoré umožňuje tímovú spoluprácu na API dokumentácii, verzionovanie špecifikácií a integráciu s CI/CD nástrojmi. Pre väčšinu testerov je ale kľúčový predovšetkým Swagger UI, ten nájdeš priamo v projekte, bez potreby akéhokoľvek predplatného.
Swagger vs. OpenAPI: Aký je medzi nimi rozdiel?
Toto je jedna z najčastejších otázok a zároveň zdroj zámen. Odpoveď je jednoduchá: OpenAPI je špecifikácia (štandard), Swagger je sada nástrojov, ktoré s touto špecifikáciou pracujú.
Pôvodne sa riešenie volalo Swagger Specification, teda názov Swagger označoval zároveň nástroj aj formát. Po prechode pod konzorcium OpenAPI Initiative, na ktorom sa podieľali firmy ako Google, Microsoft či IBM, sa formát nazýva OpenAPI Specification (OAS). Značka Swagger zostala obchodným menom pre nástroje.
Zjednodušene: keď hovoríš o formáte súboru (YAML alebo JSON popis API), hovoríš o OpenAPI Specification. Keď hovoríš o nástrojoch, ktoré tento formát čítajú a pracujú s ním, hovoríš o Swagger.
Aktuálna verzia je OpenAPI Specification 3.2.1, vydaná 10. septembra 2026. Celú špecifikáciu OpenAPI nájdeš na spec.openapis.org. Staršie projekty môžeš stále vidieť so Swagger 2.0. Pojmy OpenAPI a Swagger sa v praxi často zamieňajú, ale dnes neoznačujú tú istú vec: OpenAPI je špecifikácia a Swagger označuje nástroje, ktoré s ňou pracujú.
Vieš, že…
…názov Swagger vznikol skôr ako sám štandard OpenAPI? Pôvodne sa formát volal Swagger Specification a až v roku 2015 ho spoločnosť SmartBear darovala konzorciu OpenAPI Initiative. Odvtedy je formát otvoreným štandardom a Swagger zostal len ako značka pre nástroje.
Hlavné nástroje Swagger ekosystému
Swagger nie je jeden nástroj, ale ekosystém troch základných komponentov, ktoré pokrývajú celý životný cyklus API. Každý z nich má v práci testera vlastné miesto, niektoré používaš denne, iné príležitostne. Pozrime sa na ne postupne.
Swagger UI: Interaktívna API dokumentácia
Swagger UI je pravdepodobne nástroj, s ktorým sa ako tester stretneš najčastejšie. Ide o webovú aplikáciu, ktorá načíta OpenAPI Specification súbor a vizualizuje ho ako prehľadnú, interaktívnu dokumentáciu priamo v prehliadači. Naživo si ho môžeš vyskúšať na petstore.swagger.io, demo prostredí s ukážkovým API.
Swagger UI umožňuje:
- prehliadať všetky dostupné API endpointy (koncové body API) na jednom mieste,
- vidieť, aké parametre každý endpoint prijíma a čo vracia,
- priamo z prehliadača odoslať reálny request (požiadavku) na server,
- zobraziť response (odpoveď servera) vrátane HTTP status kódu a tela odpovede,
- testovať autentifikáciu (Bearer token, API key, OAuth2).
Z pohľadu testera je najväčšia výhoda to, že nepotrebuješ nič inštalovať. Ak má projekt Swagger UI, stačí otvoriť URL (najčastejšie /swagger-ui alebo /api-docs) a máš okamžitý prístup k celej API dokumentácii aj k možnosti manuálneho testovania. Je to v podstate vstupná brána testera do sveta API.
Druhá výhoda pre testerov je konzistentnosť. API dokumentácia v Swagger UI je generovaná priamo z kódu, čo znamená, že na rozdiel od manuálne písaných Word dokumentov odráža aktuálny stav systému. Keď vývojár pridá nový endpoint alebo zmení parametre, dokumentácia sa automaticky aktualizuje. Pre testera to znamená, že nemusíš riešiť, či to, čo čítaš, je ešte platné.
Swagger Editor: Online nástroj na písanie API špecifikácií
Swagger Editor je online editor (dostupný na editor.swagger.io), kde môžeš písať a upravovať OpenAPI Specification súbory vo formáte YAML alebo JSON. Editor funguje v reálnom čase, na ľavej strane píšeš kód špecifikácie, na pravej strane vidíš, ako vyzerá výsledná dokumentácia.
Hlavné funkcie Swagger Editor:
- real-time validácia, teda okamžité upozornenie na syntaktické chyby v OpenAPI súbore (swagger validator),
- podpora YAML aj JSON formátov (YAML je čitateľnejší, JSON rozšírenejší),
- import existujúceho OpenAPI súboru z URL alebo zo súboru,
- export hotovej špecifikácie pre ďalšie použitie,
- online verzia bez nutnosti inštalácie, popri nej existuje aj lokálna Docker verzia pre offline použitie.
Pre testera je Swagger Editor užitočný najmä vtedy, keď chceš pochopiť štruktúru API pred testovaním, alebo keď potrebuješ overiť, či API špecifikácia zodpovedá skutočnému správaniu systému. Toto je samo o sebe zaujímavý typ testu, tzv. contract testing, čiže overenie, že implementácia zodpovedá dohodnutej zmluve (OpenAPI súboru). Ak API vracia pole, ktoré v špecifikácii nie je definované, alebo naopak chýba pole, ktoré definované je, ide o nesúlad, ktorý by tester mal zachytiť.
Swagger Codegen: Automatické generovanie kódu z API špecifikácie
Swagger Codegen je nástroj, ktorý berie OpenAPI Specification súbor ako vstup a automaticky generuje kód, serverový skeleton alebo klientskú knižnicu pre rôzne programovacie jazyky (Java, Python, TypeScript, Go, C# a desiatky ďalších).
Pre testera má konkrétny praktický prínos: môžeš z neho automaticky vygenerovať testovacieho klienta pre dané API. Namiesto ručného písania HTTP requestov pre každý endpoint Codegen vygeneruje triedu alebo knižnicu, ktorú zavoláš priamo v testovacích skriptoch. Ušetrí to množstvo kódu a znižuje riziko chýb pri manuálnom zadávaní endpointov a parametrov.
Praktický príklad: predstav si, že testuješ REST API s dvadsiatimi endpointmi. Ručné písanie HTTP klientov pre každý z nich je zdĺhavé a náchylné na preklepy. Swagger Codegen ti z jedného OpenAPI súboru vygeneruje klientsku knižnicu v Pythone, Jave alebo TypeScripte, podľa toho, aký jazyk používaš v testoch. Výsledok: namiesto hodín manuálnej práce máš funkčného klienta za niekoľko minút.
Odporúčame ti…
V nových projektoch siahni rovno po OpenAPI Generator (openapi-generator.tech), open-source forku Swagger Codegen s aktívnejšou komunitou a širšou podporou jazykov. Je plne kompatibilný s OpenAPI Specification, takže prechod je bez bolesti.
Ako používať Swagger pri testovaní API
V praxi to vyzerá takto. Nasledujúci postup predpokladá, že projekt, na ktorom pracuješ, má Swagger UI dostupné cez prehliadač. Ak nie je, opýtaj sa vývojárov, väčšina moderných frameworkov (Spring Boot, NestJS, FastAPI, ASP.NET) dokáže Swagger UI vygenerovať automaticky s minimálnou konfiguráciou.
Krok 1: Otvor Swagger UI
Opýtaj sa vývojárov alebo pozri popis projektu (README) na URL, kde je Swagger dostupný. Typické adresy sú /swagger-ui, /swagger-ui.html, /api-docs alebo /swagger. Po otvorení uvidíš zoznam všetkých dostupných HTTP endpointov zoskupených podľa kategórií (tagov).
Krok 2: Vyber endpoint a pozri jeho definíciu
Klikni na ľubovoľný endpoint, napríklad GET /users. Swagger UI ti zobrazí: aké parametre endpoint prijíma (povinné vs. voliteľné), aký formát má mať telo requestu (request body), a aké responses môže server vrátiť (200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error).
Krok 3: Klikni „Try it out“ a odošli request
Tlačidlo „Try it out“ aktivuje editovateľné polia, kde môžeš vyplniť parametre a odoslať reálny request na server. Swagger UI ti zobrazí: curl príkaz, ktorý by ekvivalentne vykonal rovnaký request, URL requestu, HTTP response kód (napr. 200, 404, 500) a telo response v JSON formáte.
Krok 4: Validuj výsledok
Tu prichádza testerov kritický pohľad: porovnaj, čo API vrátilo, s tým, čo by vrátiť malo podľa dokumentácie a požiadaviek. Skontroluj status kód, štruktúru JSON odpovede, prítomnosť povinných polí, dátové typy. Ak API vráti 200, ale chýba povinné pole, je to chyba, aj keď status kód je správny. API testy sú bežnou súčasťou UAT testovania, kde overuješ, či systém ako celok spĺňa biznis požiadavky, a Swagger UI ti pri tom uľahčí prvotné manuálne overenie každého endpointu.
Krok 5: Testuj hraničné prípady a negatívne scenáre
Swagger UI je skvelý nielen na overenie happy path scenárov, ale aj na rýchle testovanie chybových stavov. Skús odoslať request bez povinného parametra, mal by prísť response 400 Bad Request. Skús zavolať endpoint bez autorizačného tokenu, očakávaný výsledok je 401 Unauthorized. Skús zadať nesprávny dátový typ (napr. text namiesto čísla). Swagger UI ti pri každom pokuse okamžite ukáže, aký response server vrátil, takže tieto základné negatívne testy dokážeš spraviť bez jediného riadku kódu.
Manuálne overenie v prehliadači je pritom len prvý krok. Ak chceš na API testy nadviazať systematicky, pozri si, ako funguje API testing a aké typy testov na jednotlivé vrstvy rozhrania nasadzujeme v msg life.
Praktické odporúčanie: pri nástupe do nového projektu si vždy ako prvé nájdi Swagger URL. Ak projekt Swagger nemá, opýtaj sa prečo. Absencia API dokumentácie je sama o sebe signál: buď je projekt starší a dokumentácia zaostáva za kódom, alebo tím jednoducho ešte nezaviedol tento štandard. V oboch prípadoch ide o priestor pre zlepšenie, na ktoré môže upozorniť práve tester. Ak ťa zaujímajú ďalšie nástroje a jazyky pre testovanie, pozri si aj náš článok o Gherkin, ďalšom formáte, ktorý testeri využívajú na popis testovacích scenárov v čitateľnej forme.
Swagger vs. Postman: Kedy použiť ktorý nástroj?
Toto je jedna z najpraktickejších otázok, ktoré si testeri kladú. Krátka odpoveď: Swagger a Postman nie sú konkurenti, sú to komplementárne nástroje, ktoré sa navzájom dopĺňajú.
| Kritérium | Swagger UI | Postman |
|---|---|---|
| Primárny účel | dokumentácia a dizajn API | testovanie a automatizácia |
| Inštalácia | nie (funguje v prehliadači) | áno (desktop app alebo web) |
| Manuálne testovanie | áno, priamo v UI | áno, pokročilejšie možnosti |
| Automatizácia testov | obmedzená | rozsiahla (Collections, Runners, CI/CD) |
| Správa prostredí | nie | áno (dev, staging, prod) |
| Kolaborácia tímu | cez SwaggerHub (platená) | áno (Workspaces) |
| Kde ho nájdeš | priamo v projekte na /swagger-ui | inštaluješ samostatne |
| Najlepší pre | pochopenie API, rýchly manuálny test | regresné testy, testovaciu automatizáciu |
Typický workflow testera vyzerá takto. Swagger UI použiješ na začiatku, keď chceš rýchlo pochopiť, čo API ponúka a ako funguje jednotlivý endpoint. Potom otvoríš Postman, kde si nastavíš prostredie (staging/prod URL, autentifikačné tokeny), vytvoríš kolekciu testov a spustíš ich v rámci CI/CD pipeline.
A teraz dobrá správa pre testerov. Postman priamo podporuje import z OpenAPI Specification. To znamená, že môžeš zobrať Swagger súbor projektu a importovať ho do Postmanu, všetky endpointy sa automaticky vytvoria ako requesty. Ušetrí to hodiny manuálnej práce. Celý postup je jednoduchý: v Postmane klikni na Import, vlož URL Swagger súboru alebo nahraj YAML/JSON súbor a kolekcia so všetkými endpointmi je okamžite k dispozícii. Odtiaľ môžeš pridávať testovacie skripty, nastavovať prostredia a spúšťať kolekciu cez CI/CD pipeline.
FAQ: Často kladené otázky o Swagger
Aký je rozdiel medzi Swagger a OpenAPI?
OpenAPI je štandard (špecifikácia formátu), Swagger je sada nástrojov. OpenAPI Specification (OAS) definuje, ako má vyzerať popis API v YAML alebo JSON formáte. Swagger nástroje tento formát čítajú, vizualizujú a spracúvajú. V bežnej reči sa pojmy často zamieňajú, ale technicky ide o dve rôzne veci.
Čo je to REST API?
REST API je rozhranie, cez ktoré si aplikácie vymieňajú dáta pomocou protokolu HTTP. Z pohľadu testera je podstatné, že každý endpoint má dopredu daný tvar požiadavky aj odpovede, takže sa dá overiť proti špecifikácii. Presne to popisuje OpenAPI súbor a sprístupňuje Swagger UI.
Je Swagger zadarmo?
Áno, hlavné Swagger nástroje, Swagger UI, Swagger Editor a Swagger Codegen, sú open-source a zadarmo. SwaggerHub, cloudová platforma pre tímy, má platené plány, ale pre individuálne použitie je dostupná aj bezplatná verzia.
Dá sa Swagger Editor používať online bez inštalácie?
Áno. Swagger Editor online beží na editor.swagger.io priamo v prehliadači, stačí doň vložiť alebo napísať OpenAPI súbor. Pre offline prácu alebo interné špecifikácie existuje aj lokálna Docker verzia s rovnakým rozhraním.
Ako otestujem API cez Swagger UI?
Postup je krátky a vystačíš si so štyrmi krokmi:
- Otvor Swagger UI na URL /swagger-ui alebo /api-docs projektu.
- Vyber endpoint, ktorý chceš otestovať, a klikni naň.
- Klikni „Try it out“, vyplň parametre a stlač „Execute“.
- Skontroluj HTTP status kód a telo response a porovnaj ho s očakávaným výsledkom.
Aký je rozdiel medzi Swagger a Postman?
Swagger (UI) slúži primárne na dokumentáciu a rýchly manuálny test priamo v projekte. Postman je samostatný nástroj zameraný na testovanie a automatizáciu, umožňuje spravovať prostredia, vytvárať testovacie kolekcie a spúšťať ich v CI/CD. V praxi sa používajú spolu: Swagger na pochopenie API, Postman na systematické testovanie.
Potrebujem pri práci s nástrojom Swagger vedieť programovať?
Nie. Swagger UI ovládaš klikaním v prehliadači, request odošleš a odpoveď servera prečítaš bez jediného riadku kódu. Programovanie oceníš až pri Swagger Codegen, kde vygenerovaný klient smeruje do testovacích skriptov. Na manuálne testovanie API ti stačí orientácia v štruktúre JSON a YAML, teda vedieť, čo je pole, objekt a dátový typ.
Swagger ako konkurenčná výhoda testera
Swagger (resp. OpenAPI ekosystém) je dnes de facto štandard pre dokumentáciu REST API v modernom softvérovom vývoji. Ak pracuješ v QA a testovanie API je (alebo bude) súčasťou tvojej práce, znalosť týchto nástrojov ti dá konkurenčnú výhodu na pohovore aj v dennej praxi.
Začni od Swagger UI, je to najrýchlejší spôsob, ako spoznať API nového projektu bez čítania stoviek strán dokumentácie a bez vypytovania sa vývojárov na každý detail. Keď sa cítiš sebaisto, pozri si Swagger Editor a pochop, ako OpenAPI Specification vyzerá zvnútra. To ti pomôže lepšie porozumieť štruktúre testov a identifikovať medzery v dokumentácii. Ak ti chýba kontext o samotnej úlohe testera, pozri si, ako začať ako IT tester junior bez skúseností.
Swagger sám testy nespúšťa. V automatizovaných behoch sa napája na CI/CD pipeline a dopĺňa ho Selenium, ktoré pokrýva používateľské rozhranie tam, kde Swagger končí pri API vrstve. Práve spojenie API a UI testovania patrí k tomu, čo hľadáme v našich otvorených pozíciách v oblasti testingu.
