Jan Mikoláš
Slovník pojmů
OpenAPI
OpenAPI je popis kontraktu HTTP API. Není to samotné API ani náhrada rozhodnutí o jeho obchodním chování.
Stručná definice
Společný, strojově čitelný popis HTTP rozhraní.
OpenAPI Specification (OAS) popisuje HTTP API nezávisle na programovacím jazyce. Dokument ve formátu JSON nebo YAML může říct člověku i nástroji, jaké URL, HTTP metody, parametry, těla požadavků, odpovědi a jaké bezpečnostní mechanismy nebo požadavky kontrakt deklaruje.
Samotné API je běžící rozhraní a REST je architektonický styl, kterým může, ale nemusí být navrženo. OpenAPI je naproti tomu formální kontrakt. Užitečný je jen tehdy, když odpovídá skutečnému chování služby a změny se spravují stejně pečlivě jako zdrojový kód.
Použití
K čemu OpenAPI slouží
Dobře udržovaný kontrakt snižuje dohady mezi vývojáři, integrátory a provozem.
- interaktivní dokumentace endpointů pro integraci e-shopu, skladu nebo marketplace
- validace tvaru příchozích požadavků a vracených odpovědí
- generování typovaných klientů, testovacích vstupů nebo výchozího serverového kódu
- contract-first návrh, kdy se nejprve domluví rozhraní, a code-first přístup, kdy popis vzniká z aplikace
- kontrola kompatibility kontraktu před zveřejněním nové verze API
Praktický příklad
Kontrakt pro získání objednávky
Marketplace integrátor předem ví, který identifikátor má poslat, jak vypadá úspěšná odpověď a jak odlišit neexistující objednávku od neplatného tokenu. Server i klient mohou tento malý úsek kontraktu validovat.
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
responses:
'200':
description: Objednávka
content:
application/json:
schema: { $ref: '#/components/schemas/Order' }
'404': { description: Objednávka nenalezena }Jak funguje
Od operace k ověřitelnému kontraktu
Dokument soustředí pravidla rozhraní do jedné verze, kterou mohou používat lidé i nástroje.
- Základ dokumentu Informace o API, serverech a globálním zabezpečení vymezí, čeho se kontrakt týká.
- Paths a operations Cesty a metody, například GET /orders/{id}, popisují konkrétní operace.
- Vstupy a výstupy Parameters, request body, responses a schemas určují tvar i význam dat.
- Sdílené části Components znovu používají schémata, odpovědi či security schemes bez kopírování.
- Kontrola změny Validátor nebo CI porovná dokument a implementaci; nekompatibilní změna potřebuje řízený přechod.
Důležité pojmy
Z čeho se kontrakt skládá
Popsaný datový tvar a skutečný význam operace jsou stejně důležité.
Schemas a examples
Schéma určuje očekávané typy, povinná pole a strukturu. Příklad pomáhá integrátorovi, ale nesmí suplovat pravidla ani obsahovat citlivá data.
Responses
Každý významný výsledek má mít popsaný HTTP status, hlavičky a tělo včetně chybového formátu.
Security schemes
Kontrakt může určit například HTTP bearer token nebo OAuth 2.0 flow. Samotný zápis ale nenastaví oprávnění ani bezpečné ověření.
Kompatibilita
Přidání nepovinného pole bývá méně rizikové než odstranění pole, změna typu nebo nově povinný vstup. Vždy záleží na pravidlech klientů.
Vztah k podobným pojmům
OpenAPI není REST ani implementace.
Jednotlivé části spolu souvisejí, ale neřeší tutéž vrstvu.
- API
- Rozhraní a jeho provozní smlouva; OpenAPI je jeden způsob, jak HTTP část popsat.
- REST API
- Návrhový styl HTTP rozhraní. OpenAPI lze použít pro RESTful i jiné HTTP API.
- Validátor
- Ověří strukturu podle specifikace, ne správnost cen, skladu ani oprávnění v obchodním procesu.
- Generovaný kód
- Urychlí opakující se části klienta či serveru, ale nenahradí obchodní logiku, chybové scénáře ani code review.
Výhody a omezení
Přesnější dohoda, ne automaticky kvalitní integrace.
Přínosy
- jeden čitelný zdroj pro dokumentaci, testy a klienty
- dřívější odhalení rozdílu mezi očekávaným a skutečným datovým tvarem
- znovupoužití schémat a jednotných chybových odpovědí
- lepší posouzení kompatibility před vydáním změny
Rizika
- zastaralý dokument vytváří falešnou jistotu
- příliš obecné schema ztrácí hodnotu pro validaci
- generovaný skeleton může zakrýt nutnost návrhu business pravidel
- změna kontraktu bez přechodného období může rozbít klienty
Hranice použití
Kontrakt má smysl tam, kde API žije déle než jeden endpoint.
OpenAPI je zvlášť užitečné pro veřejná, partnerská a týmová API, kde se mění více klientů nezávisle na serveru. U malé interní jednorázové operace může být přínos menší, přesto se vyplatí popsat vstup, odpověď a chybu alespoň stručně.
Specifikace neodpovídá na otázku, zda lze objednávku změnit, jak se řeší timeout nebo zda je operace idempotentní. Tyto vlastnosti musí být explicitně navrženy, popsány a ověřeny mimo samotný generátor dokumentace.
Na co myslet
Kontrakt udržovat jako součást aplikace.
Při změně se kontroluje nejen syntaktická validita dokumentu, ale i dopad na uživatele API.
- pojmenované a stabilní operationId, datové modely a chyby
- příklady odpovídající reálným, ale anonymizovaným datům
- verzování a deprekační období pro nekompatibilní změny
- ověření požadavků i odpovědí v integračních testech
- jasně popsané zabezpečení, limity a chování při chybě
Časté otázky
Co se o OpenAPI často plete
Je OpenAPI totéž co Swagger?
Ne. OpenAPI je specifikace. Nástroje původně spojené se jménem Swagger dnes často dokument OpenAPI zobrazují, validují nebo z něj generují kód.
Musí být API REST, aby mělo OpenAPI?
Nemusí. OpenAPI popisuje HTTP rozhraní; jeho URL a operace nemusí splnit všechny principy RESTu.
Nahradí generovaný klient ruční testování integrace?
Ne. Klient může správně serializovat data, ale nezaručuje dostupnost služby, oprávnění, obchodní pravidla ani správné zpracování chyb.
Je přidání pole vždy kompatibilní?
Ne vždy. Záleží na tom, zda klienti odmítají neznámá pole, jak se pole interpretuje a zda je nově povinné.
Jak OpenAPI používám v praxi
Rozhraní beru jako dlouhodobou dohodu mezi systémy.
U API a integrací řeším kontrakty, validaci, chybové stavy i dohledatelnost navazujících synchronizací.