Mielőtt implementálnánk, tervezzük meg a rendszert
Sok csapat csak az implementáció után generál API-contractot. Az előre megtervezett interfész közös forrást ad a backendnek, a frontendnek, a QA-nak és a szolgáltatás consumereinek, amikor még olcsó javítani az integrációs hibákat.

Kezdjük a contracttal
Sok csapatnál az API-contract még mindig csak mellékterméke a fejlesztésnek. Megírják az endpoint handlereket, hozzáadják a DTO-kat és a validációt, majd a futó alkalmazásból próbálnak dokumentációt kinyerni. Amikor a frontend, a QA és a többi szolgáltatás elkezdi az integrációt, kiderül, hogy mindenki másként értelmezte a nullable mezőket, az enumokat, az edge case-eket és a hibaformátumokat. A klienskód addigra több repóba szóródott szét.
Amíg kicsi a rendszer, ezzel még együtt lehet élni. Platformméretben viszont fékezi a delivery-t.
A spec-first fejlesztés ezeket a döntéseket az implementáció elé hozza. Ha a contract teljes jogú forrásfájl, a design nem marad rejtve a controllerkódban: a csapatok review-zhatják, kódot generálhatnak belőle, és több rendszerben is újrahasznosíthatják.
A contract a delivery egyik alapja
Az OpenAPI, az AsyncAPI és a JSON Schema együtt emberek és eszközök számára egyaránt olvashatóan írja le a rendszerhatárt.
A határ leírása nem merül ki a mezőnevekben és a primitív típusokban. Rögzíti a megengedett payloadokat és a kötelező mezőket, valamint a formátumra és a szerkezetre vonatkozó megkötéseket. Ide tartoznak a hibák, az autentikáció, a szerepkörök és scope-ok, a kompatibilitási szabályok, az eseménypayloadok, valamint a backend és a frontend közös modelljeinek jelentése is.
Ha a határt előre definiáljuk, a csapatoknak nem az implementáció részleteiből kell utólag kikövetkeztetniük, mi volt a terv.
Hogyan működik a code-first a gyakorlatban
A code-first megközelítés gyorsnak tűnik: megírjuk az endpointot, annotáljuk, majd a framework metaadataiból dokumentációt generálunk. Egyes eszközök a DTO-kból vagy a TypeScript-típusokból a sémát is kikövetkeztetik. Ez kényelmes, kis szolgáltatásnál hasznos is, de a designt csak akkor lehet review-zni, amikor már kód lett belőle.
Nagyobb rendszerekben viszont a dokumentáció minősége a framework konvencióin múlik. A generált contract inkább a transport szerkezetét tükrözi, mint a tervezői szándékot. Idővel eltér egymástól a backend- és a frontendmodell, következetlen lesz a sémák újrahasznosítása, duplikálódik a validáció, a klienskönyvtárakban pedig hiányosak a típusok, vagy nincs runtime-ellenőrzés.
A code-first nem eleve rossz választás, csak ilyenkor könnyen az implementáció közben, véletlenül születnek meg az interfészdöntések. A spec-firstnél akkor lehet review-zni őket, amikor még olcsó változtatni rajtuk.
A JSON Schema többre képes, mint amire a legtöbb csapat használja
Sok csapat közvetve már használ JSON Schemát: ott van az OpenAPI-ban, a validációs eszközökben, az űrlapgenerálásban és a konfigurációk ellenőrzésében. Mégis többnyire csak technikai részletnek tartják, nem a rendszerhatárok közös leírásának.
A modern backendplatformokon a JSON Schema az egyik leghatékonyabb eszköz a rendszerhatárok leírására. Az adatszerkezetek és megkötések géppel olvasható modelljéből API-specifikáció, runtime-validáció, generált típusok, frontendűrlapok, mockok, tesztfixture-ök, contractdiffek és közös platformkönyvtárak is készülhetnek, így a delivery-lánc minden eleme ugyanabból a leírásból dolgozik.
Spec-first platformszinten
A legnagyobb hasznát a Fizz-backendplatform építésekor láttuk: ott a spec-first nem szolgáltatásonként eltérő ízlés kérdése volt, hanem a platform része.
Az OpenAPI-dokumentum statikus YAML-fájlként a service forráskódjában van. Handlereket, típusokat és validátorokat generálunk belőle, az AJV pedig a backenden és a frontenden is fut. A CI naprakészen tartja a backend consumerek, a frontendalkalmazások és a tesztek HTTP-klienseit. A tesztek így mockokkal futhatnak, anélkül hogy URL-eket, metódusokat vagy payloadokat kellene beégetni.
A kliensek a contractból generálódnak, ezért a consumereknek nem kell kézzel összerakniuk a service-hívásokat. A backendvalidáció és a frontend ugyanazokra a sémákra épül.
A fejlesztők szerint javult a developer experience, mert nem kell fejben tartaniuk az interfész részleteit. Egy-egy hívásnál kevés időt nyerünk, de sok szolgáltatásban és repóban ez összeadódik.
Az OpenAPI-dokumentum a service forráskódjában legyen
Sok code-first megoldásban az API-dokumentum a futó alkalmazásból generálódik. Így a contract a kódtól függ, és gyakran csak fordítás vagy indulás után érhető el megbízhatóan.
A service forrásába commitolt statikus OpenAPI YAML megfordítja ezt a függőséget. A specifikáció már a service futása előtt létezik, pull requestben review-zható, és önállóan lintelhető és validálható. Már az implementáció befejezése előtt épülhet rá kódgenerálás, breaking change-ellenőrzés, dokumentációpublikálás és tesztelés. A contract így a fejlesztés kiindulópontja lesz, amelyet a platform tart karban.
Vizuál: code-first és spec-first
flowchart TD
A[Handlerek és DTO-k írása] --> B[Dokumentáció generálása frameworkmetaadatokból]
B --> C[A consumerek találgatják a viselkedést]
C --> D[Integrációs hibák későn derülnek ki]
D --> E[Kód, dokumentáció és kliensek foltozása]
F[Először az OpenAPI / AsyncAPI megtervezése] --> G[Sémák és viselkedés review-ja]
G --> H[Típusok, validátorok, handlerek, kliensek generálása]
H --> I[Implementáció a jóváhagyott contract alapján]
I --> J[Korábbi integráció, kevesebb eltérés]
A generált kliensek kiváltják a duplikált interfészkódot
A generált kliensek időt takarítanak meg, de a nagyobb előnyük a konzisztencia.
Generált kliensek nélkül a consumerek kézzel másolják le az interfészt. Helyben rakják össze az útvonalakat és a queryparamétereket, emlékezetből választanak HTTP-metódust, az auth headereket pedig kliensenként másként kötik be. A request- és response-típusok gyakran hiányosak, a hibakezelés esetleges, a tesztek beégetett endpointrészleteket tartalmaznak, az eventalapú rendszerekben pedig az egyes komponensek idővel eltérő topicneveket és payloadszerkezeteket használnak.
Ahány másolat, annyi hely, ahol az implementáció és a consumerek eltérhetnek egymástól.
Ha a CI gondoskodik róla, hogy a kliensek mindig a friss contractból generálódjanak, az ilyen hibák nagy része eltűnik. A consumerek közvetlenül a contractból generált artifactokat használják.
Nálunk ez a tesztelést is javította. A generált klienseket end-to-mock tesztekben is használjuk, vagyis a tesztek ugyanazt a contractból generált felületet használják, mint a production consumerek. A tesztekhez így nem kell duplikált URL, kézzel írt fetch wrapper vagy magic string a metódusok és az útvonalak megadásához.
Ritkábban törnek el a tesztek, mert nem tartalmazzák az interfész egy második, kézzel írt változatát.
A típusok nem védenek runtime-ban
A TypeScript a fejlesztés közben segít végiggondolni, milyen adatot várunk, de runtime-ban nem validálja a külső inputot. Hibás payload érkezhet másik szolgáltatásból, régebbi klienstől, csak részben frissített consumertől vagy külső integrációból.
Ha a handlerek, a kliensek és az űrlapok ugyanazokból a sémákból épülnek, sokkal könnyebb egységesen tartani a runtime-validációt a rendszerhatárokon.
Backendoldalon a bejövő requesteket kell validálni, és néha azt is ellenőrizni kell, hogy a kimenő adatok megfelelnek-e a contractnak. A frontenden a felhasználói inputot kell validálni, és ellenőrizni kell, hogy az elküldendő payload megfelel-e az API-contractnak.
Ha az AJV mindkét oldalon fut, runtime-ban is ellenőrizzük azt, amit a típusok csak fejlesztés közben írnak le.
A típusrendszer leírja, mit vár a saját kódunk, a validátor pedig ellenőrzi, mi lépte át ténylegesen a rendszerhatárt, ezért mindkettőre szükség van.
Ugyanazok a sémák a frontendet is segíthetik
A spec-firstről többnyire backendes szemmel beszélünk, pedig ugyanazokat a sémákat a frontend és az admin tooling is használhatja.
Ha az API-kat JSON Schema-alapú contractok írják le, és ezek a sémák a frontendnek is elérhetők, nemcsak kliensgenerálásra használhatók.
Például a JSON Forms jelentősen gyorsíthatja az adminfelületek fejlesztését.
Egy teljes, ügyfeleknek szóló frontendhez a sémából generált felület általában túl kezdetleges. Belső eszközöknél, admin backoffice-nál, üzemeltetési felületeknél, konfigurációs képernyőknél és workflow-űrlapoknál viszont a schema-driven UI sok ismétlődő munkát kiválthat.
Akkor működik igazán jól, ha tisztán elkülönítjük, mi miért felel:
- JSON Schema írja le a data contractot és a validációs szabályokat
- UI Schema írja le az elrendezést és a megjelenítést
- AJV validálja az űrlapadatot ugyanazzal a sémával, amelyet az API-contract is használ
Így a teljes lánc összhangban marad:
- A backend contract definiálja, mi számít érvényes payloadnak.
- A frontendűrlap ugyanezekből a sémákból generálható, vagy legalább nagyrészt rájuk épülhet.
- A UI schema irányítja a renderelést, a csoportosítást, a widgeteket és a layoutot.
- A payload küldés előtt validálható.
- A backend fogadáskor ugyanazt a szerkezetet validálja.
Így nem kell minden rétegben külön, kézzel újraimplementálni a mezőket, a szabályokat és a szerkezeti elvárásokat.
JSON Forms és schema-driven adminfelületek
A belső platformokon gyorsan rengeteg üzemeltetési űrlap gyűlik össze: termékattribútum-szerkesztők, árazási konfigurációk, integrációs beállítások, szabály- és policy-szerkesztők, merchant onboarding, supporteszközök és feature-konfigurációs panelek.
Ezek a felületek fontosak, de ritkán ezeken múlik, hogy a termék kitűnik-e. Pontosnak, karbantarthatónak és könnyen módosíthatónak kell lenniük; a mezők többségéhez nem kell egyedi UX.
JSON Forms-szal vagy hasonló eszközökkel a szerkezetet és a validációt JSON Schemában definiáljuk, a megjelenítést UI schemával irányítjuk, az űrlap pedig teljesen kompatibilis marad a backend contracttal.
A közös modell miatt nincs szükség duplikált meződefiníciókra, és a validációs szabályok egy helyen maradnak. Gyorsabban készülnek el az új adminfelületek, olcsóbb követni a sémaváltozásokat, a beküldött adat ritkábban tér el az API-contracttól, és a fejlesztők hamarabb kiismerik a belső eszközöket.
Ott használjuk újra a contractmodellt, ahol ezzel ismétlődő UI-munkát spórolunk meg.
Vizuál: schema-driven folyamat az API-tól az admin UI-ig
flowchart TD
A[OpenAPI + JSON Schema] --> B[Generált backend handlerek és validátorok]
A --> C[Generált típusos kliensek]
A --> D[Frontendűrlapmodell]
D --> E[UI Schema vezérli a layoutot és a widgeteket]
E --> F[JSON Forms rendereli az admin UI-t]
F --> G[AJV validál frontendoldalon]
G --> H[Request küldése generált klienssel]
H --> I[AJV validál újra backendoldalon]
Az event contractok láthatóvá teszik a rejtett csatolást
A spec-first különösen fontos, ha a rendszer nem tisztán szinkron.
HTTP-nél legalább láthatók az interfészek: vannak útvonalak, metódusok, státuszkódok. Üzenetalapú rendszereknél a rendszer növekedésével egyre nehezebb átlátni a felületet. Ahogy szaporodnak a topicok, és a payloadok egyeztetés nélkül változnak, hasonló események jelennek meg eltérő jelentéssel, a consumerek pedig dokumentálatlan feltételezésekre támaszkodnak.
Az AsyncAPI és a következetesen újrahasznosított sémák láthatóvá teszik ezeket a függőségeket.
Event-driven rendszerekben a kétértelműség veszélyesebb, mert a hibák gyakran késve és szétszórtan jelentkeznek. Egy téves feltételezés nem mindig jár látványos hibával: csendben is hibás működést okozhat a downstream rendszerekben, vagy úgy ronthat el egy integrációt, hogy az okát drága felderíteni.
Az explicit event contract rögzíti az üzenet payloadját és jelentését, a felelős csapatot, a verziózás módját, a correlation ID-kat, a kompatibilitási szabályokat és a példákat.
Ahogy a HTTP API-knál, itt is a forráskódban tárolt contractra épülhet a validáció, a review, a generálás és a governance. Enélkül az event-driven rendszerben észrevétlen csatolások halmozódnak fel, amelyek csak akkor derülnek ki, amikor valamelyik consumer hibásan kezd működni.
A biztonsági követelmények is a contractba valók
Sok rendszerben csak az interfész megtervezése után implementálják az authorizationt. Az endpointok csak a kódban kapnak védelmet, a szerepköröket nem írják le egyértelműen, a policy-k pedig szétszóródnak annotációk, middleware-ek és service-enként eltérő konvenciók között.
Ha a scope-ok, az auth-sémák és a védett műveletek a contractban szerepelnek, több minden egyszerűbb lesz:
- a biztonsági követelmények korábban review-zhatók
- a generált artifactok egységesen értelmezhetik az auth-követelményeket
- a consumercsapatok tudják, milyen credential vagy scope kell
- a hiányosságok már a design review során kiderülhetnek, nem csak a rollout után
Ez nem helyettesíti az authorization gondos megtervezését, de a biztonsági követelményeket az interfész mellé teszi, ahol a reviewerek és a consumerek is látják.
Stabil contract mellett a csapatok párhuzamosan dolgozhatnak
Amint a contract elég stabil:
- a backend implementálhatja a handlereket
- a frontend használhatja a generált klienseket
- a QA előkészítheti a teszteseteket és a fixture-öket
- a specifikációból mockok készülhetnek
- az integrációs tesztelés korábban elindulhat
- a consumerszolgáltatásokat a contract alapján lehet fejleszteni, mielőtt a provider elkészülne
A közös contract annyira csökkenti a bizonytalanságot, hogy lehet párhuzamosan dolgozni. A backendnek, a frontendnek, a QA-nak és a consumerszolgáltatásoknak nem kell megvárniuk a provider deployolását.
A CI gondoskodik róla, hogy a contract legyen a mérvadó
Ha a CI ügyel arra, hogy a specifikáció érvényes legyen, és a generált artifactok naprakészek maradjanak, sokkal nehezebb véletlenül megkerülni a folyamatot.
Egy kiforrott CI-ban jellemzően ezek az ellenőrzések futnak:
- OpenAPI- vagy AsyncAPI-validáció
- a sémák lintelése
- a breaking change-ek felismerése
- handlerek, típusok, validátorok és kliensek generálása
- annak ellenőrzése, hogy a generált kód commitolva vagy publikálva van
- tesztek futtatása generált kliensekkel és mockokkal
Ezek az ellenőrzések teszik a contractot mérvadóvá, így a contract-first nem azon múlik, hogy mindenki emlékszik-e rá, és betartja-e.
Vizuál: a spec-first platform folyamata
flowchart TD
A[OpenAPI / AsyncAPI frissítése] --> B[PR-review]
B --> C[Séma és példák validálása]
C --> D[Breaking change-ellenőrzés]
D --> E[Típusok, validátorok, handlerek, kliensek generálása]
E --> F[Tesztek futtatása generált kliensekkel és mockokkal]
F --> G[Service és contract artifactok publikálása]
Mikor nem működik a spec-first
Ha a sémák gyengék, a generált artifactok rossz minőségűek, vagy a specifikációt bürokratikus tehernek tekintik, a folyamat nehézkes lesz, és kevés hasznot hoz.
Tipikusan akkor bukik meg, ha:
- a spec megvan, de senki nem tekinti mérvadónak
- a fogadó oldal nem validál a contract alapján
- hiányoznak a példák
- gyenge minőségű a generált kód
- homályosak a verziózási és kompatibilitási szabályok
- a csapatok a lényegtelen dolgokat is túl aprólékosan modellezik
- senki nem felel a contract életciklusáért
Ott vezessük be a spec-firstet, ahol a contract számít. Tartsuk olvashatónak a sémákat, csak olyan artifactokat generáljunk, amelyek munkát váltanak ki, vagy eltérést előznek meg, a CI-ban tegyük kötelezővé a folyamatot, és a contract review-t vegyük olyan komolyan, mint a design review-t.
A consumerek számával együtt nő a megtérülés
Egy termék életének elején szinte bármilyen módon lehet interfészt tervezni, mert kevés a consumer, és gyors a visszajelzés. Ahogy szaporodnak a szolgáltatások, a frontendek, a csapatok és a környezetek, egyre több helyen kell kompatibilisnek maradni, és erősebb governance-re, több üzemeltetési eszközre, megbízhatóbb automatizálásra van szükség.
Az interfész ilyenkor már a platform része, nem helyi implementációs részlet. A spec-first akkor térül meg, ha a delivery pipeline egészében a contractra épül a kódgenerálás, a validáció és a tesztelés.
Építsünk a contractra
A spec-firstnél a contract már a fejlesztés elején kész, így az eszközök, a tesztek, a validátorok, a kliensek és a csapatok ugyanarra a forrásra támaszkodhatnak.
A JSON Schema összekötheti az API designt, a runtime-biztonságot, a kliensgenerálást, az admin UI-generálást és a platformgovernance-t. Ha csak validációs segédeszköznek tekintjük, a lehetőségei nagy része kihasználatlan marad.
A Fizz-backendplatformon ugyanazokra a sémákra épül a backend, a frontend, a tesztek és az admin UI.
Ha már használunk OpenAPI-t, AsyncAPI-t vagy JSON Schemát, a következő lépés: írjuk meg először a contractot, és építsük rá a rendszert.
Ha egy meglévő rendszernél nem világos, melyik határon érdemes kezdeni, erre is választ ad a kéthetes architektúrareview: a 90 napos roadmap megnevezi, mely contractokat kell elsőként formalizálni.