Ismerkedés a Swagger -rel

A Swagger egy népszerű eszközkészlet és szabvány az API-k dokumentálására, tervezésére és tesztelésére. Az informatika világában elsődlegesen a RESTful API-k kezelésére használják, és hozzájárul az API-fejlesztési folyamat egyszerűsítéséhez, valamint a fejlesztők és tesztelők közötti együttműködés javításához.

A Swagger kulcsszerepet játszik az API-k életciklusában, az első tervezési lépésektől a tesztelésen és fejlesztésen át az éles üzemeltetésig. Rugalmas és könnyen használható eszközei miatt széles körben alkalmazzák a modern szoftverfejlesztésben.

A Swagger alapvetően az API specifikációk kezelésére és dokumentálására épül. Az OpenAPI Specification (OAS) segítségével pontosan és szabványosan definiálhatók az API végpontjai, paraméterei, válaszai és egyéb részlete

Mire használható a Swagger

1. API specifikációk létrehozása

A Swagger az OpenAPI Specification (OAS) szabványt használja az API-k leírására. Ez egy JSON vagy YAML alapú nyílt formátum, amely egyértelműen meghatározza az API végpontokat, metódusokat, paramétereket, válaszokat és egyéb részleteket.
Segít az API-k következetes tervezésében, különösen nagy projektekben.

2. Automatikus API-dokumentáció

A Swagger eszközeivel automatikusan generálható könnyen olvasható és vizuálisan átlátható API-dokumentáció.
Ez a dokumentáció tartalmazza:
- A végpontok URL-jeit és HTTP metódusait.
- Paramétereket és azok típusait.
- Példákat a bemenetekre és kimenetekre.

3. Interaktív API-tesztelés

A Swagger UI egy interaktív felületet biztosít, ahol a fejlesztők és tesztelők közvetlenül tesztelhetik az API-kat a dokumentációban.
- Például: Egy gombnyomással elküldhető egy kérés, és azonnal látható a válasz (státuszkód, válasz body stb.).

4. Mock API-k létrehozása

Az API-k fejlesztése előtt a Swagger mock API-kat generálhat az API specifikációk alapján.
Ez lehetővé teszi a front-end fejlesztők számára, hogy az API működését szimulálva dolgozhassanak, mielőtt a back-end elkészül.

5. Kódgenerálás

A Swagger Codegen vagy az OpenAPI Generator segítségével automatikusan generálható klienskód (pl. Java, Python, JavaScript) és szerver oldali kód sablonok.
Ez csökkenti a manuális kódírási hibákat és gyorsítja a fejlesztési folyamatot.

6. API verziókezelés

A Swagger segít a különböző API-verziók követésében és dokumentálásában, így könnyebb karbantartani a kompatibilitást a régebbi verziókkal.

7. Csapatmunka támogatása

Egy Swagger-dokumentáció megosztható a csapat többi tagjával, beleértve a fejlesztőket, tesztelőket és az üzleti oldal képviselőit, ami egyszerűsíti a kommunikációt és az API-k közös használatát.

Swagger eszközök és platformok

Swagger Editor:
- Egy online vagy offline szerkesztő, ahol YAML vagy JSON formátumban hozható létre és szerkeszthető az OpenAPI specifikáció.
Swagger UI:
- Egy interaktív API-dokumentáció, amely a Swagger specifikációt vizuálisan jeleníti meg.
- Lehetővé teszi az API végpontok tesztelését közvetlenül a böngészőben.
Swagger Codegen:
- Automatikusan generál klienskódot vagy szerver oldali kódot az API specifikáció alapján.
Swagger Hub:

Egy felhőalapú platform, amely lehetővé teszi az API-k tervezését, megosztását és együttműködést egy központi helyen.

Előnyök

Egyszerűbb fejlesztés és tesztelés:
- Az automatizált dokumentáció és a kódgenerálás jelentősen csökkenti az API-fejlesztési időt.
- Az interaktív tesztelés lehetővé teszi a gyors hibakeresést.
Átláthatóság:
- A Swagger által generált dokumentáció egyértelműen bemutatja az API funkcionalitását, amely segíti mind a fejlesztőket, mind a nem technikai felhasználókat.
Integráció más eszközökkel:
- A Swagger kompatibilis számos CI/CD rendszerrel, mint például a Jenkins, Travis CI vagy Docker.
Szabványosítás:
- Az OpenAPI szabvány révén biztosítható, hogy az API-k dokumentálása és használata konzisztens legyen.
Csapatmunka elősegítése:
- A Swagger megkönnyíti a különböző szerepkörök együttműködését, beleértve a front-end és back-end fejlesztőket, tesztelőket és üzleti elemzőket.

Dokumentumok szerkesztése a Swagger segítségével

Swagger Editor használata

A Swagger Editor egy online vagy offline elérhető eszköz, amely lehetővé teszi az OpenAPI specifikációk szerkesztését YAML vagy JSON formátumban.
Főbb funkciók:
- Interaktív szerkesztés: Ahogy szerkeszted a fájlt, az eredmény azonnal megjelenik az előnézeti panelen.
- Hibajavítási támogatás: Az editor jelzi a szintaktikai vagy logikai hibákat.
- Példa API-struktúrák: Alapértelmezett minta API specifikáció, amit testre szabhatunk.

Telepítési lehetőségek:

Online: Használd a Swagger Editor online verzióját.
Offline: Telepítsd helyileg Node.js segítségével:
```
---- bash

npm install -g swagger-editor
```

Specifikációk létrehozása YAML formátumban

A Swagger dokumentáció YAML formátumban könnyen olvasható és strukturált. Egy egyszerű példa egy API specifikációra:

---- yaml

openapi: 3.0.0
info:
  title: Példa API
  description: Ez egy példa az OpenAPI 3.0 használatára.
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Felhasználók lekérdezése
      responses:
        '200':
          description: Sikeres válasz
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: John Doe

Főbb elemek a YAML fájlban:

info: Az API-ról szóló alapvető információk (cím, verzió, leírás).
servers: Az API elérhetőségének URL-jei.
paths: Az API végpontjai és metódusai (pl. GET, POST).
components: Sémák, amelyeket a végpontok hivatkoznak (pl. objektumok, típusok).

Utak és megfigyelések létrehozása

Útvonalak (Paths) létrehozása

Az útvonalak az API végpontjait definiálják, beleértve a metódusokat és az ezekhez tartozó válaszokat:

Példa egy GET végpontra:

---- yaml

/users:
  get:
    summary: Felhasználók listázása
    responses:
      '200':
        description: Sikeres válasz

További HTTP-módszerek: POST, PUT, DELETE, stb.

Megfigyelések hozzáadása

A válaszokhoz és útvonalakhoz különféle leírások, példák és validációk adhatók:

Válasz formátuma:

--- yaml

responses:
  '404':
    description: Nem található
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string

Dokumentáció hozzáadása

A dokumentáció az API-k átláthatóságát növeli, és könnyíti a fejlesztők közötti együttműködést.

Hozzáadandó elemek:

Leírások: Minden végponthoz és válaszhoz részletes magyarázatokat adhatsz.

Példák: Adj meg mintákat bemenetekre és válaszokra.

Példa:

---- yaml

requestBody:
  description: Új felhasználó adatai
  required: true
  content:
    application/json:
      example:
        name: "Jane Doe"
        email: "jane.doe@example.com"

Sémák hozzáadása az OAS-fájlhoz

A sémák (schemas) az API válaszainak vagy bemeneteinek struktúráját határozzák meg:

Példa egy séma hozzáadására:

---- yaml

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number

A sémák újra felhasználhatók az útvonalak definícióiban a $ref kulcsszóval:

---- yaml

responses:
  '200':
    description: Termék lista
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Product'

A SwaggerHub használata

A SwaggerHub egy felhőalapú platform az API-k tervezésére, dokumentálására és kezelésére.

Főbb funkciók:

Kollaboráció: Csapatok közösen dolgozhatnak API specifikációkon.
Verziókezelés: API verziók követése és karbantartása.
Publikálás: Az API specifikációk közzététele a csapat számára, vagy nyilvánosan elérhetővé tétele.
Integráció: CI/CD rendszerekkel és egyéb eszközökkel történő könnyű integráció.

SwaggerHub használatának lépései:

Hozz létre egy projektet a SwaggerHub platformon.
Importáld az API specifikációt YAML vagy JSON formátumban.
Használj csapathoz rendelt munkaterületeket a hatékony együttműködéshez.

Oktatás, háttér anyagok:

https://learn.microsoft.com/hu-hu/training/modules/improve-api-developer-experience-with-swagger/

https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle

Online swagger editor: https://editor.swagger.io/

IT, BI, DWH, DM, AI

Keresés ebben a blogban