Swagger editor alapok

Funkciók és használat

A Swagger Editorban nincs hagyományos automatikus kódkiegészítés (intellisense) a natív felületen, mint például a fejlettebb IDE-kben (pl. VS Code). Azonban néhány tipp és trükk segíthet a hatékonyabb szerkesztésben:

1. Automatikus Javaslatok (alapértelmezett viselkedés)

Az Editor bizonyos esetekben automatikusan felkínál javaslatokat, főleg ha már létező mezőkbe írunk.
Ha egy már létező struktúra alá írsz (pl. paths vagy components), akkor sokszor automatikusan megjelenik néhány lehetőség.

2. Séma és Struktúra követése

A Swagger Editor a YAML szintaxist követi, ezért ha helyesen kezded el írni az elemeket, az Editor sokszor felkínálja a következő lehetséges kulcsszavakat.

3. Billentyűkombinációk

A Ctrl + Space billentyűkombinációval előhozhatod a javaslatok listáját, ha az Editor támogatja azt az adott mezőnél.
Egyes böngészőkben (pl. Chrome) ez néha nem működik megfelelően, ilyenkor próbáld ki az Alt + Space kombinációt.

4. Alternatív Megoldások

Ha a Swagger Editorban nem elégedett a kódkiegészítéssel, használhatod a következő alternatívákat:

VS Code OpenAPI Plugin: A Visual Studio Code-hoz elérhető OpenAPI plugin jobb kódkiegészítést biztosít.
SwaggerHub: A SwaggerHub prémium szolgáltatásai fejlettebb szerkesztési funkciókat kínálnak.

5. JSON helyett YAML

A YAML szintaxis használata gyakran több javaslatot hoz elő, mint a JSON formátum.

OpenAPI Dokumentáció Felépítése

Az OpenAPI dokumentáció hierarchikus felépítésű, ahol minden szinten más-más szerepkörrel rendelkező kulcsok és objektumok találhatók.

Főbb Szintek és Szerepkörök

Szint	Kulcs	Szerepkör
1. Alapszint	`openapi`, `info`, `servers`	Alapinformációk az API-ról és a kiszolgálókról.
2. Végpont szint	`paths`	Az API végpontjait és az elérhető HTTP metódusokat határozza meg.
3. Művelet szint	HTTP metódusok (`get`, `post`, `put`, `delete`, stb.)	A konkrét műveletek leírása az egyes végpontokon.
4. Paraméterek	`parameters`, `requestBody`, `responses`	Bemeneti és kimeneti adatok meghatározása.
5. Adatséma szint	`components`	Újrafelhasználható objektumok, például sémák és válaszok definiálása.

OpenAPI Dokumentáció Részletezése

1. Alapszint: Metaadatok és Szerverek

Az OpenAPI dokumentáció az alapvető információkkal kezdődik:

-- yaml

openapi: 3.0.0
info:
  title: My API
  description: Példa API dokumentáció
  version: 1.0.0
servers:
  - url: https://api.example.com/v1

openapi: Az OpenAPI verzióját adja meg.
info: Az API általános metaadatai (cím, leírás, verzió).
servers: A szerverek listája, ahol az API elérhető.

2. Végpont szint: Paths

Az API végpontjainak és azok elérési útjainak leírása:

--- yaml

paths:
  /users:
    get:
      summary: Felhasználók listázása
      responses:
        '200':
          description: Sikeres lekérdezés

paths: A végpontok gyűjteménye.
/users: Egy konkrét API útvonal.

3. Művelet szint: HTTP Metódusok

Minden végpont alá külön HTTP műveleteket sorolhatunk:

--- yaml

paths:
  /users:
    post:
      summary: Új felhasználó létrehozása
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Felhasználó sikeresen létrehozva

get, post, put, delete, stb.: A támogatott HTTP metódusok.
summary: A művelet rövid leírása.
responses: A válaszok típusa és tartalma.

4. Paraméterek és Válaszok

Az API végpontokhoz kapcsolódó paraméterek és válaszok leírása:

---yaml

parameters:
  - name: userId
    in: path
    required: true
    schema:
      type: string
responses:
  '200':
    description: Lekérdezés sikeres

parameters: Bemeneti adatok, pl. URL paraméterek vagy kérés törzse.
responses: A HTTP válaszok típusai és szerkezete.

5. Adatséma szint: Components

Újrafelhasználható sémák és válaszok definiálása:

---yaml

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

components: A globálisan elérhető objektumok gyűjteménye.
schemas: Az API-ban használt adatszerkezetek.

Összefoglaló Táblázat

Szint	Kulcs	Leírás	Példa
Alapszint	`openapi`, `info`, `servers`	Az API verziója, metaadatai és elérhető szerverek.	OpenAPI verzió: 3.0.0, szerver: `https://api.example.com`
Végpont szint	`paths`	Az API végpontok listája és elérési útjai.	`/users` végpont
Művelet szint	HTTP metódusok	A végpontokon végrehajtható műveletek (pl. GET, POST).	`get`, `post`
Paraméterek	`parameters`, `requestBody`, `responses`	Bemeneti és kimeneti adatok részletes leírása.	`userId`, `requestBody`, `responses`
Adatséma szint	`components`, `schemas`	Újrafelhasználható objektumok és adatszerkezetek meghatározása.	`User` objektum

Tippek az OpenAPI Dokumentációhoz

Újrafelhasználhatóság: Használj components részt az objektumsémák újrafelhasználására.
Konzisztencia: Törekedj a kulcsok és objektumok egységes használatára.
Generálás: Használj OpenAPI eszközöket (pl. Swagger UI vagy Redoc) a vizualizációhoz.
Érvényesítés: Ellenőrizd a dokumentum helyességét az OpenAPI Validator segítségével.

YAML szintaxis alapok

A YAML (Yet Another Markup Language, később átnevezve YAML Ain’t Markup Language) egy adatleíró nyelv, amelyet gyakran használnak konfigurációs fájlokhoz, adatcsere formátumokhoz és API dokumentációkhoz (például OpenAPI specifikációkhoz).
A YAML egyszerűsége és olvashatósága miatt népszerű, különösen olyan esetekben, ahol az emberi olvashatóság fontos szempont.

🔑 Alapfogalmak és Szabályok

Behúzás (Indentation): A YAML a behúzásokat szóközökkel kezeli (tabulátor használata nem ajánlott).
Kulcs-érték párok: Az adatok kulcs-érték párokként jelennek meg, kettősponttal elválasztva.
Adattípusok: Szöveg, szám, logikai értékek, listák, objektumok, null értékek.
Kommentek: A kommentek # jellel kezdődnek.
Dokumentum elválasztó: A --- jel különálló YAML dokumentumokat választ el.

📝 YAML Alapszintaxis

🔷 1. Egyszerű kulcs-érték párok

---yaml

név: John Doe
kor: 30
város: Budapest

A kulcsok és értékek között kettőspont található.
Az érték lehet szám, szöveg vagy logikai érték.

🔷 2. Listák használata

🔹 Egyszerű lista

--- yaml

hobbik:
  - futás
  - olvasás
  - programozás

🔹 Egy soros lista

---yaml

színek: [piros, zöld, kék]

🔷 3. Beágyazott objektumok (Hierarchikus adatok)

--- yaml

személy:
  név: John Doe
  életkor: 30
  lakcím:
    város: Budapest
    irányítószám: 1011

A beágyazott objektumok szóközökkel vannak behúzva.
A mélység meghatározására két szóköz a legelterjedtebb konvenció.

🔷 4. Több dokumentum egy fájlban

--- yaml

---
név: Első dokumentum
típus: bemutató
---
név: Második dokumentum
típus: teszt

A --- jel elválasztja a különböző dokumentumokat.

🧩 Adattípusok a YAML-ban

Típus	Példa	Leírás
Sztring	`név: "John Doe"`	Szöveges érték, idézőjel nem mindig szükséges.
Szám	`kor: 30`	Egész vagy lebegőpontos szám.
Logikai	`aktív: true`	Logikai értékek: `true`, `false`.
Null	`érték: null`	Üres vagy `null` értékek.
Lista	`- alma`	Tömb vagy felsorolás.
Objektum	`kulcs: érték`	Kulcs-érték páros, hasonló a JSON objektumokhoz.

📝 YAML Haladó Szintaxis

🔷 1. Több soros szöveg

🔹 Több soros string megtartott sortöréssel (Pipe jel: `|`)

---yaml

leírás: |
  Ez egy hosszú leírás,
  amely több sorból áll,
  és megtartja a sortöréseket.

🔹 Több soros string eldobott sortöréssel (Nagykötőjel: `>`)

---yaml

cím: >
  Ez egy hosszú sor,
  amely folytatódik a következő sorban,
  de sortörés nélkül.

🔷 2. Hivatkozások és horgonyok

🪝 Horgonyok és referenciák használata

---yaml

alap_adatok: &alap
  város: Budapest
  ország: Magyarország

személy1:
  név: John Doe
  <<: *alap

személy2:
  név: Jane Smith
  <<: *alap

A & jel horgonyt hoz létre, a * jel pedig hivatkozik rá.
A << operátor az objektumok beillesztésére szolgál.

🛠️ YAML Használati Esetek

💼 1. Konfigurációs Fájlok

🔧 Docker Compose példája

---yaml

version: '3.9'
services:
  web:
    image: nginx
    ports:
      - "80:80"
  db:
    image: postgres
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

📋 2. Adatmodellek és API dokumentáció (OpenAPI)

--- yaml

openapi: 3.0.0
info:
  title: API dokumentáció
  version: 1.0.0
paths:
  /users:
    get:
      summary: Felhasználók listázása
      responses:
        '200':
          description: Sikeres lekérdezés

🔁 3. CI/CD Pipeline (GitLab CI)

---yaml

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - echo "Building project..."

test-job:
  stage: test
  script:
    - echo "Running tests..."

deploy-job:
  stage: deploy
  script:
    - echo "Deploying application..."

Gyakori Hibák és Tippek

Behúzási Hibák: Tabulátor helyett használj szóközöket (általában 2 vagy 4).
Értékek típusai: Ne keverd a számokat és a szövegeket. Például id: 123 és id: "123" különbözőek.
Idézőjelek: Ha a sztring különleges karaktereket tartalmaz, használj idézőjeleket (" vagy ').
Sortörések kezelése: Használd a | és a > jeleket a hosszú szövegek kezelésére.

JSON Szintaxis

A Swagger Editorban (vagy OpenAPI Editorban) a dokumentáció JSON formátumban is elkészíthető. A JSON alapú OpenAPI dokumentáció szerkezete és felépítése alapvetően azonos a YAML alapúval, azonban a szintaxis eltér.

JSON-t akkor érdemes használni, ha automatizált feldolgozást vagy gépi olvasást végzel, mivel a JSON könnyebben feldolgozható programozási nyelveken keresztül.

🔑 JSON Szabályok

Objektumok: Kapcsos zárójelek között ({}), kulcs-érték párok formájában.
Tömbök: Szögletes zárójelek között ([]).
Kulcsok: Mindig dupla idézőjelek között kell lenniük.
Értékek: Lehetnek sztringek, számok, logikai értékek, objektumok, tömbök vagy null.
Vesszők: Minden kulcs-érték pár után (kivéve az utolsót) vessző van.

💡 JSON alapú Swagger dokumentáció Felépítése

📋 1. Alapszint: Metaadatok és Szerverek

---json

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "description": "Példa API dokumentáció",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

openapi: Verziószám (pl. 3.0.0).
info: Az API általános információi (cím, leírás, verzió).
servers: Az API által elérhető szerverek listája.

🔗 2. Végpont szint: Paths

---json

"paths": {
  "/users": {
    "get": {
      "summary": "Felhasználók listázása",
      "responses": {
        "200": {
          "description": "Sikeres lekérdezés"
        }
      }
    }
  }
}

paths: Az API végpontjainak és HTTP metódusainak listája.
/users: Egy konkrét végpont (útvonal).
get: A végponton elérhető HTTP művelet.

📝 3. Művelet szint: HTTP Metódusok

---json

"paths": {
  "/users": {
    "post": {
      "summary": "Új felhasználó létrehozása",
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      },
      "responses": {
        "201": {
          "description": "Felhasználó sikeresen létrehozva"
        }
      }
    }
  }
}

post: A POST művelet leírása a /users végponton.
requestBody: Az API művelet által várt bemeneti adat.
responses: A művelet által visszaadott válaszok.

🔎 4. Paraméterek és Válaszok

---json

"paths": {
  "/users/{userId}": {
    "get": {
      "summary": "Felhasználó adatainak lekérése",
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "Sikeres válasz",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        }
      }
    }
  }
}

parameters: Az útvonalparaméterek (itt a userId).
in: Meghatározza, hogy az adat honnan származik (pl. path).
required: Kötelező paraméter jelzése.

🛠️ 5. Adatsémák és Komponensek

---json

"components": {
  "schemas": {
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      },
      "required": ["id", "name"]
    }
  }
}

components: Globálisan elérhető objektumok és adatsémák gyűjteménye.
schemas: Újrafelhasználható objektumsémák.
required: Kötelező mezők meghatározása.

🚀 Swagger Editor Használati Tippek JSON Formátumban

Szerkezet ellenőrzése: Az Editor automatikusan kiemeli a hibákat és javaslatokat ad.
Automatikus formázás: Használj formázó eszközöket a JSON kód olvashatóságának növelésére.
Kód kiegészítés: A Swagger Editor automatikusan felajánlja a kulcsokat és értékeket.
Interaktív tesztelés: A Swagger UI integrált tesztelési lehetőséget biztosít.

📝 Swagger Editor: Kód Kiegészítés Aktiválása

A Swagger Editorban a kód kiegészítés a következőképpen érhető el:

Új sorban állva: Nyomd meg a Ctrl + Space kombinációt (Windows/Linux) vagy Cmd + Space (Mac), hogy megjelenjen a kiegészítési lista.
Automatikus ajánlások: Ha egy kulcsot kezdesz írni (pl. "responses":), az Editor automatikusan felkínálja a lehetséges értékeket.
Hibaellenőrzés: A piros vagy sárga figyelmeztetések segítenek a hibák gyors észlelésében.

📝 JSON vs YAML Swagger Dokumentációk

Tulajdonság	JSON	YAML
Szintaxis	Szögletes és kapcsos zárójelek, idézőjelek	Egyszerű, tiszta formátum, behúzásokkal
Emberi olvashatóság	Nehezebb	Könnyebb, áttekinthetőbb
Gép által feldolgozható	Könnyen olvasható és feldolgozható	Nehezebb gépi feldolgozás
Hibaellenőrzés	Szintaxis hibák könnyen felismerhetők	Behúzási hibák gyakoriak

💡 Összegzés

A JSON alapú Swagger dokumentáció áttekinthető, strukturált és könnyen géppel feldolgozható, de az emberi olvashatóság kissé nehezebb a YAML-hoz képest. Az Editor automatikus kiegészítési funkciói nagyban segítik a fejlesztést, különösen komplex API-k esetében.

IT, BI, DWH, DM, AI