Swagger használat egy API fejlesztés során

A Swagger egy olyan eszközkészlet, amely segít a fejlesztőknek API-dokumentáció létrehozásában, szerkesztésében és használatában az OpenAPI specifikációi szerint.

A Swaggerrel már nem szükséges manuálisan hosszadalmas API-dokumentumokat írni: a megoldás képes beolvasni a kód annotációiban megadott API szerkezetét, és automatikusan API specifikációvá konvertálni.

Ráadásul a Swagger olyan felhasználói felületet biztosít, amely interaktív API-dokumentációt generál, amely lehetővé teszi a felhasználók számára, hogy teszteljék az API-hívásokat a böngészőben.

A Swagger fő összetevői a következők:

Swagger Editor API specifikációk írásához és szerkesztéséhez,
Swagger UI interaktív API-dokumentáció létrehozásához,
Swagger Codegen kiszolgálócsonkok vagy ügyfélkönyvtárak generálásához az API-hoz.

Ha összeállítottuk az előző fejezet szerint az OpenAPI (Swagger) dokumentációt YAML formátumban, akkor az alábbi lépéseken érdemes végig haladni a fejlesztési és tesztelési folyamat során:

🚀 1. Validálás és Szintaxis Ellenőrzés

✅ Swagger Editor

A Swagger Editor valós időben ellenőrzi a YAML szintaxist, és hibajelzéseket ad.
Ha hibát látsz, részletes leírást kapsz róla az editor alján.

✅ Online Validátorok

Használhatsz online validátorokat is, például:

Swagger Editor beépített validációs funkcióját.
Swagger Inspector: URL-alapú API tesztelésre és validálásra.
SwaggerHub: Verziókezelést és kollaborációt is támogat.

https://redocly.github.io/redoc/ https://validator.swagger.io/

✅ Parancssori Validálás

Telepítsd az OpenAPI CLI-t:
```
--bash

npm install -g @redocly/cli
```
Futtasd a validációt:
```
---bash

openapi lint api.yaml
```
A lint parancs segít megtalálni a szerkezeti hibákat és szabálytalanságokat.

🛠️ 2. Generált Klienskód és Szerveroldali Skeleton

✅ Automatikus Generálás

Használhatsz automatikus kódkészítő eszközöket, például a Swagger Codegen-t vagy az OpenAPI Generator-t:
```
--bash

npm install -g @openapitools/openapi-generator-cli
```

Klienskód generálása (pl. Python):

---bash

openapi-generator-cli generate -i api.yaml -g python -o ./client

Szerveroldali skeleton generálása (pl. Java Spring):

bash

openapi-generator-cli generate -i api.yaml -g spring -o ./server

Az automatikusan generált kódot felhasználhatod alapnak a tényleges fejlesztéshez.

🧪 3. Tesztelés és Debuggolás

🧩 Swagger UI

Használd a Swagger UI-t interaktív API tesztelésre:
- Helyi futtatás:
```
---bash

docker run -p 8080:8080 -e SWAGGER_JSON=/api/api.yaml -v $(pwd):/api swaggerapi/swagger-ui
```
- Megnyitás a böngészőben: http://localhost:8080

🛠️ Postman Integráció

Importáld az OpenAPI fájlt a Postman-ba:
- Import → Upload Files → Válaszd ki az api.yaml fájlt
Az OpenAPI definíció alapján automatikusan létrejönnek a kérés típusok, melyeket azonnal tesztelhetsz.
Használhatod a Postman Environment funkcióját a változók kezelésére.

📊 4. API Tesztelési Stratégiák

🔧 Egységtesztelés (Unit Testing)

Minden végpontot külön tesztelj kliensoldalon, és ellenőrizd a válasz típusát és struktúráját.

🔄 Integrációs Tesztelés

Teszteld az API és más rendszerek integrációját (pl. adatbázis vagy külső szolgáltatások).

🚦 Teljesítménytesztelés

Használhatsz eszközöket, mint a JMeter vagy a k6:
```
---bash

k6 run loadtest.js
```
Ellenőrizd az API válaszidejét és a skálázhatóságot.

📝 5. Dokumentáció és Verziókezelés

📚 Dokumentáció Generálás

A Swagger UI alapból generál interaktív dokumentációt, de használhatod a Redoc-ot is:
```
---bash

npx redoc-cli bundle api.yaml
```
A generált HTML fájl statikus webhelyen is elérhetővé tehető.

🔄 Verziókezelés

A YAML fájlokat tárold verziókövető rendszerben (pl. Git), és használj ágkezelést a különböző fejlesztési fázisok elkülönítésére.

💡 6. CI/CD Integráció

Integráld az OpenAPI validálást és tesztelést a CI/CD folyamatba:

GitHub Actions vagy Jenkins pipeline:

---yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2
      - name: Validate OpenAPI
        run: openapi lint api.yaml
      - name: Run Tests
        run: npm test

Automatikusan futtathatók a validálások és a tesztek minden commit után.

🔥 Gyakorlati Tipp

Mindig tartsd naprakészen az OpenAPI dokumentációt! Ha változás történik az API-ban, azonnal frissítsd a YAML fájlt, különben gyorsan elavult dokumentációval találhatod magad szembe.

📝 Összegzés

A Swagger (OpenAPI) dokumentáció fejlesztése és tesztelése iteratív folyamat. A jól strukturált YAML definíciók validálása és tesztelése kritikus fontosságú a sikeres API-fejlesztéshez. Az automatikus kódgenerálás, a Postman integráció és a CI/CD folyamatok alkalmazása jelentősen növeli a fejlesztési hatékonyságot és a minőséget.

📝 1. API Tervezés elvek

🌟 API Célja:

CRUD műveletek felhasználók kezelésére:
- GET /users: Felhasználók listázása
- POST /users: Új felhasználó létrehozása
- GET /users/{id}: Felhasználó adatainak lekérése
- PUT /users/{id}: Felhasználó adatainak módosítása
- DELETE /users/{id}: Felhasználó törlése

✍️ 2. OpenAPI Dokumentáció létrehozása (YAML)

API Specifikáció (api.yaml)

---yaml

openapi: 3.0.0
info:
  title: Felhasználókezelő API
  version: 1.0.0
  description: Felhasználók kezelése (CRUD műveletek)

servers:
  - url: http://localhost:3000

paths:
  /users:
    get:
      summary: Felhasználók listázása
      responses:
        '200':
          description: Sikeres lekérdezés
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Új felhasználó létrehozása
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Felhasználó létrehozva

  /users/{id}:
    get:
      summary: Egy felhasználó lekérése ID alapján
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Felhasználó adatai
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Nem található
    put:
      summary: Felhasználó módosítása
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Sikeres módosítás
    delete:
      summary: Felhasználó törlése
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Sikeres törlés

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name
        - email

🛠️ 3. Automatikus Kódbázis Generálása

✅ Swagger Codegen Telepítés

---bash

npm install -g @openapitools/openapi-generator-cli

✅ Szerveroldali Skeleton Generálás (Node.js)

---bash

openapi-generator-cli generate -i api.yaml -g nodejs-express-server -o server

✅ Klienskód Generálás (JavaScript)

---bash

openapi-generator-cli generate -i api.yaml -g javascript -o client

🧪 4. Tesztelés

📝 Swagger UI használata

Telepítés Docker segítségével:

---bash

docker run -p 8080:8080 -e SWAGGER_JSON=/api/api.yaml -v $(pwd):/api swaggerapi/swagger-ui

Elérés a böngészőben:
```
---arduino

http://localhost:8080
```
A Swagger UI lehetővé teszi az API műveletek interaktív tesztelését.

🧩 Postman használata

Importálás:
- Válaszd az Import lehetőséget a Postman-ben.
- Töltsd fel az api.yaml fájlt.
Tesztelés:

Használd az automatikusan generált kéréseket a CRUD műveletekhez.

🚦 5. Folyamatos Integráció és Tesztelés

✅ GitHub Actions példa

---yaml

name: API Validation and Tests
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Install OpenAPI Generator
        run: npm install -g @openapitools/openapi-generator-cli
      - name: Validate OpenAPI Spec
        run: openapi-generator-cli validate -i api.yaml
      - name: Run Tests
        run: npm test

📊 6. Összegzés és Táblázat

Fázis	Tevékenység	Eszköz	Eredmény
API Tervezés	CRUD műveletek megtervezése	Swagger Editor, OpenAPI Spec	YAML alapú specifikáció
API Dokumentáció	OpenAPI dokumentáció létrehozása	Swagger Editor	Részletes leírás a végpontokról
Kódgenerálás	Skeleton és klienskód automatikus generálása	OpenAPI Generator	Express.js szerver, JavaScript kliens
API Tesztelés	Interaktív tesztelés és validálás	Swagger UI, Postman	API válaszok és műveletek ellenőrzése
CI/CD Integráció	Automatikus validálás és tesztelés	GitHub Actions	Automatikus hibajelzés és tesztelés push-kor

💡 Összegzés

Tervezés és Dokumentáció: Használd a Swagger Editort a dokumentáció készítéséhez és az API struktúrájának megtervezéséhez.
Kódgenerálás: Használd az OpenAPI Generator-t a szerver és kliens kód előállítására.
Tesztelés: A Swagger UI és a Postman segít az interaktív tesztelésben és hibakeresésben.
CI/CD Integráció: Automatikusan ellenőrizd a dokumentáció helyességét és az API működését.

IT, BI, DWH, DM, AI