Swagger / OpenAPI kódgenerálás

A fejlesztés során a contract first szemléletet követjük, melynek egyik előnye, hogy előtérbe helyezi a tervezést, valamint minimalizálja a figyelmetlenségből eredő hibákat a szerver és kliensek közötti egységes kontrakt miatt.

Ezen felül garantálja, hogy minden szerveroldali API funkcionalitáshoz tartozik kontrakt is, így lehetővé téve az azonnali kliensoldali integrációt. Ráadásul, mivel az API leíró fájl bővítése az első lépés a fejlesztések során, így lehetővé teszi, hogy a kontrakt megírása után a kliens és szerveroldali fejlesztés párhuzamosan tudjon zajlani.

1. Technikai megvalósítás

Az OpenAPI definíció verziókövetéséhez az api repository tartozik.

Az api repository külön releaselhető és a megfelelő definiciós fájlok (openapi-backend.yml, openapi-frontend.yml, openapi-mbl.yml) a backend repository GitLab package registry-jébe release-elődnek.

A backend, frontend projektek azok release során, verziószám alapján tudják meghivatkozni a release-hez szükséges api verziót.

Ezt a repositoryt lokális fejlesztői környezetben, fájlrendszer szinten érik el és használják a backend és a frontend projektek. Azt, hogy az api repository a fejlesztéshez szükséges állapoton/branchen álljon a fejlesztő feladata biztosítani.

2. Definíciós fájlok

A definíciós fájlok YML kiterjesztésű OpenAPI specifikációnak megfelelően írt fájlok. Az OpenApi specifikáció megtalálható itt.

A definíciós fájlokat az api repositoryban tartjuk karban.

Fontos

Csak a specifikáció által elfogadott és támogatott definíciókat használjuk az OpenAPI fájl írásakor, illetve semmi esetben ne használjunk nyelvfüggő elemeket. A cél az, hogy a definíciós fájl nyelvfüggetlenül felhasználható és általános legyen a kliens és a szerveroldali fejlesztők számára.

Törekedjünk arra, hogy a kontrakt a lehető legtöbb információt tartalmazza, minél több információ legyen közös a szerver és kliensek között, ezzel is törekedve a lehető legmagasabb minőségű implementációra.

2.1 Definíciós fájlok szeparálása

A definíciós fájlokat funkciók szerint hozzuk létre. Azaz, egy funkcióhoz tartozó összes api és séma definíció egy darab fájlba kell kerüljön.

2.1.1 Definíciós fájlok létrehozása és elnevezési konvenciója

A funkciókhoz tartozó definíciós fájlokat a feature/${funkciónév} package alá kell létrehozni.

A definíciós fájlok elnevezési konvenciója az alábbi:

${funkció-név}.yml

Pl.: feature/adminmanagement/admin-management.yml

2.1.2 Funkciófüggetlen definíciós fájlok

A common package alatt találhatóak a funkciófüggetlen definíciós fájlok:

A common/meta/meta-data.yml fájl tartalmazza a definíciós fájlokra vonatkozó metadatokat. Pl.: verziószám, projekt név stb.
A common/schema/common-schemas.yml fájl tartalmazza az általános funkciófüggetlen sémákat. Pl.: SystemMessageResponse.

2.1.3 A definíciós fájlok mergelése

A funkciónként szeparált definíciós fájlokat, illetve a common/meta/meta-data.yml és common/schema/common-schemas.yml fájlokat az openapi-merge-cli plugin segítségével mergeljük a frontend (openapi-web.yml), mobil(openapi-mbl.yml), és a backend(openapi-backend.yml) számára.

Ehhez a generate/openapi-merge-backend.json, generate/openapi-merge-web.json, generate/openapi-merge-mbl.json fájlokban kell felsorolni a mergelni kívánt definíciós fájlokat. Ebből következik, hogy amennyiben új definíciós fájlt hozunk létre, akkor azt fel kell vennünk a megfelelő merge konfigurációkban is, hogy az előállított API leíróban is benne legyen.

A definíciós fájlok mergelése a frontend projekt esetén az npm run generate, a backend projekt esetén a mvn clean package során automatikusan végrehajtódik.

2.2 Adattípusok

Figyeljünk arra, hogy mindig a lehető legpontosabban definiáljuk az adattípusokat, erre a szám típusoknál kell fokozottan figyelni, ahol a type és format kombinációját kell használnunk:

`type`	`format`	generált Java típus
number	-	BigDecimal
number	float	Float
number	double	Double
integer	-	Integer
integer	int32	Integer
integer	int64	Long

Az OpenAPI által támogatott adattípusokról bővebben olvashatsz itt.

2.3 Validációk

A definíciós fájl tartalmazza a formai validációkat is.

Szöveges mezőknél célszerű definiálni a minLength és maxLength értékeket, ezzel kiváltva a @NotBlank és hasonló Java specifikus megoldásokat.

Nem használhatók saját custom validációs annotációink sem, ezek a pattern mezővel és reguláris kifejezéssel helyettesítendők.

A reguláris kifejezéseket JavaScript szintaxis szerint kell írni, valamint a pontos egyezés kifejezéséhez ^...$ tokenek közé kell rakni kifejezést, ahol a ^ a string kezdetét, a $ pedig a string végét jelenti.

3. Kódgenerálás

Megfelelő api repository használata

A kódgenerálás előtt érdemes meggyőződni róla, hogy a megfelelő állapot van-e checkoutolva az api repositoryból. Pl.: A megfelelő branchen áll-e az api repository, illetve tartalmazza-e az általunk esetlegesen hozzáadott DTO és contract módosításokat stb.

3.1 `frontend` kódgenerálás

A frontend repositoryban a generálást egy generate npm script végzi, ami a postinstallba is be van kötve, így az npm install és npm ci utasításokat kiadva automatikusan fut. Azonban manuálisan is futtatható a generáló script az npm run generate:api parancs kiadásával.

3.2 `backend` kódgenerálás

A backend repositoryban compile idején generálódnak a DTO-k az openapi-generator-maven-plugin segítségével. Ebből következően manuálisan az mvn clean compile paranccsal generálhatóak a DTO-k.

api repository a release folyamatban

Fontos, hogy a backend és a frontend release folyamat során a repositorykban található api verziószámot a megfelelő api verziószámra kell frissíteni. Ennek részletes leírása megtalálható a release folyamat dokumentációjában.

Kódgenerálás a CI során

Amennyiben a fejlesztésünk API módosítást igényel úgy ezeket a módosításokat egy külön api branchen kell elvégeznünk.

Ahhoz, hogy a CI jobok is megtalálják azt az api branchet amivel a backend és frontend projekteket buildelniük kell, ahhoz az api branchünket ugyanazon a néven kell létrehoznunk, mint a backend és/vagy frontend feature branchünket.

A branchek elnevezési konvenciójáról részletesebben itt olvashatsz.