Web

Hogyan készíts egy API dokumentációt Swagger és Express.js párossal?

iranyonline 0

Képzeld el, hogy egy új fejlesztő csatlakozik a csapatodhoz, vagy egy külső partnerrel kell integrálódnod. Mi az első dolog, amire szükségük van, hogy megértsék és használni tudják az API-dat? Egyértelmű, részletes és naprakész API dokumentáció! Enélkül a fejlesztés lassú, hibás és frusztráló lesz. De hogyan készíthetünk olyan dokumentációt, ami egyszerre könnyen kezelhető, automatizálható és mindig aktuális? Ebben a cikkben bemutatjuk, hogyan hozhatsz létre professzionális API dokumentációt az Express.js keretrendszerhez a Swagger (pontosabban az OpenAPI specifikáció) erejével, a swagger-jsdoc és a swagger-ui-express könyvtárak segítségével.

Miért kritikus az API dokumentáció?

Az API dokumentáció nem csupán egy „jó, ha van” dolog, hanem egy elengedhetetlen komponens minden sikeres projektben. Néhány ok, amiért ennyire fontos:

  • Gyorsabb onboarding: Az új fejlesztők pillanatok alatt megérthetik az API működését, csökkentve ezzel a betanulási időt.
  • Kevesebb félreértés: Egyértelműen definiált végpontok, paraméterek és válaszok minimalizálják a kommunikációs hibákat a frontend és backend csapatok, vagy külső partnerek között.
  • Konzisztencia: Segít fenntartani az egységes API tervezési elveket az egész alkalmazásban.
  • Automatizálás: A géppel olvasható formátum lehetővé teszi tesztek, kliens kódok és egyéb eszközök automatikus generálását.
  • Tesztelhetőség: A dokumentáció alapján könnyen írhatók automatizált tesztek, vagy akár manuális tesztelés is végezhető a Swagger UI felületén keresztül.

Ismerjük meg a főszereplőket: OpenAPI (Swagger) és Express.js

Mielőtt belevágunk a gyakorlati lépésekbe, tisztázzuk a két fő eszköz, az OpenAPI és az Express.js szerepét.

OpenAPI Specification (korábbi nevén Swagger Specification)

Az OpenAPI Specification egy nyelvfüggetlen, géppel olvasható interfészleírási formátum RESTful API-k számára. Lényegében egy szabványos módszer az API-k leírására, beleértve az elérhető végpontokat, azok műveleteit (GET, POST, PUT, DELETE), a bemeneti és kimeneti paramétereket, az autentikációs módszereket és még sok mást. A „Swagger” név gyakran gyűjtőfogalomként használatos, de technikailag az OpenAPI Specification maga a szabvány, míg a Swagger Tools (Swagger UI, Swagger Editor, Swagger Codegen) az OpenAPI specifikációval való munkát segítő eszközök gyűjteménye.

A specifikációt YAML vagy JSON formátumban írjuk meg, de a swagger-jsdoc segítségével közvetlenül a kódban, JSDoc-szerű kommentek formájában is elhelyezhetjük, ami sokkal kényelmesebb és naprakészebb megoldást kínál.

Express.js

Az Express.js a Node.js egyik legnépszerűbb webes keretrendszere. Minimalista, rugalmas és robusztus, ezért ideális választás REST API-k építésére. Az egyszerűsége ellenére hatalmas közösségi támogatással rendelkezik, és számos middleware áll rendelkezésre a funkcionalitás kiterjesztésére. Pontosan ez a rugalmasság teszi lehetővé, hogy a Swagger eszközöket zökkenőmentesen integráljuk az Express.js alkalmazásokba.

Projekt előkészítése: Express.js alapok

Mielőtt elmerülnénk a Swagger konfigurációban, hozzunk létre egy alapvető Express.js projektet. Ha már van egy meglévő Express.js alkalmazásod, kihagyhatod ezt a lépést.

Először is, hozzunk létre egy új mappát a projektnek, navigáljunk bele, majd inicializáljuk az `npm`-et:

mkdir my-api-docs
cd my-api-docs
npm init -y

Ezután telepítsük az Express.js-t:

npm install express

Hozzunk létre egy `app.js` fájlt a projekt gyökerében a következő tartalommal:

// app.js
const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware, ami lehetővé teszi a JSON kérések testének feldolgozását
app.use(express.json());

// Egyszerű gyökér útvonal
app.get('/', (req, res) => {
  res.send('Üdv az Express.js API-ban!');
});

// A szerver elindítása
app.listen(PORT, () => {
  console.log(`A szerver fut a http://localhost:${PORT} címen`);
});

Most indítsd el a szervert a `node app.js` paranccsal, és látnod kell a konzolon az üzenetet. A böngésződben megnyitva a `http://localhost:3000` címet, látnod kell az „Üdv az Express.js API-ban!” üzenetet.

A Swagger UI integrálása Express.js-be

A Swagger UI egy dinamikus, interaktív dokumentációs felület, amely automatikusan generálódik az OpenAPI specifikációból. Lehetővé teszi, hogy vizuálisan böngéssz az API végpontjaid között, megtekintsd a paramétereket, sémákat, és akár közvetlenül a böngészőből küldj kéréseket az API-nak. Az Express.js-hez való integráláshoz két további csomagra lesz szükségünk:

  • swagger-ui-express: Ez a csomag Express.js middleware-ként szolgál a Swagger UI kiszolgálásához.
  • swagger-jsdoc: Ez a csomag képes feldolgozni a JSDoc-szerű kommenteket, és azokból generálni az OpenAPI specifikációt. Ez a kulcs a kód melletti dokumentációhoz!

Telepítsük ezeket a csomagokat:

npm install swagger-ui-express swagger-jsdoc

Konfiguráció és inicializálás

Hozzunk létre egy `swaggerConfig.js` fájlt a projekt gyökerében, ahol definiáljuk az OpenAPI specifikáció alapadatait és a fájlokat, amiket a swagger-jsdoc-nak át kell vizsgálnia a kommentekért:

// swaggerConfig.js
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// Swagger JSDoc opciók
const options = {
  definition: {
    openapi: '3.0.0', // Vagy '2.0' a Swagger 2.0-hoz
    info: {
      title: 'Express.js API Dokumentáció',
      version: '1.0.0',
      description: 'Egy minta API dokumentáció Swaggerrel és Express.js-szel',
      contact: {
        name: 'Támogatás',
        url: 'http://www.example.com/support',
        email: '[email protected]',
      },
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Fejlesztési szerver',
      },
      {
        url: 'https://production.example.com',
        description: 'Éles szerver',
      },
    ],
    // Biztonsági sémák definiálása, pl. JWT tokenhez
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
    },
  },
  // API végpontokat és modelleket tartalmazó fájlok.
  // Ide kell a routes és models mappák elérési útvonalát megadni.
  apis: ['./routes/*.js', './models/*.js'],
};

// Az OpenAPI specifikáció generálása
const specs = swaggerJsdoc(options);

// Exportáljuk a middleware-t
module.exports = (app) => {
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, { explorer: true }));
};

Most módosítsuk az `app.js` fájlt, hogy használja ezt a konfigurációt és az API dokumentációt kiszolgáló útvonalat:

// app.js
const express = require('express');
const app = express();
const apiDocs = require('./swaggerConfig'); // Importáljuk a swaggerConfig-ot
const PORT = process.env.PORT || 3000;

app.use(express.json());

// API útvonalak (később hozzáadjuk a routes mappát)
// Példa:
// const usersRouter = require('./routes/users');
// app.use('/users', usersRouter);

// Swagger UI beállítása
apiDocs(app);

app.get('/', (req, res) => {
  res.send('Üdv az Express.js API-ban!');
});

app.listen(PORT, () => {
  console.log(`A szerver fut a http://localhost:${PORT} címen`);
  console.log(`A Swagger UI elérhető a http://localhost:${PORT}/api-docs címen`);
});

Indítsd újra a szervert (`node app.js`). Most, ha megnyitod a `http://localhost:3000/api-docs` címet a böngésződben, egy üres Swagger UI felületet kell látnod. Üres, mert még nem dokumentáltunk egyetlen végpontot sem!

API végpontok dokumentálása JSDoc kommentekkel

Most jön a lényeg! A swagger-jsdoc lehetővé teszi, hogy közvetlenül a kódodba írd a dokumentációt, JSDoc-szerű kommentek formájában. Ez biztosítja, hogy a dokumentáció mindig naprakész legyen, amint módosítod az API-t.

Hozzunk létre egy `routes` mappát a projekt gyökerében, és azon belül egy `users.js` fájlt. Ez fogja kezelni a felhasználókkal kapcsolatos végpontokat.

mkdir routes
touch routes/users.js

Most illesszük be a következő tartalmat a `routes/users.js` fájlba. Figyeld meg a JSDoc kommenteket minden útvonal előtt:

// routes/users.js
const express = require('express');
const router = express.Router();

/**
 * @swagger
 * tags:
 *   name: Felhasználók
 *   description: A felhasználókkal kapcsolatos műveletek.
 */

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Összes felhasználó lekérdezése
 *     tags: [Felhasználók]
 *     responses:
 *       200:
 *         description: Sikeres válasz, a felhasználók listája.
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 *       500:
 *         description: Szerver oldali hiba.
 */
router.get('/', (req, res) => {
  res.json([{ id: 1, name: 'Tomi' }, { id: 2, name: 'Anna' }]);
});

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Felhasználó lekérdezése azonosító alapján
 *     tags: [Felhasználók]
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: A felhasználó egyedi azonosítója.
 *     responses:
 *       200:
 *         description: Sikeres válasz, a felhasználó adatai.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       404:
 *         description: A megadott azonosítóval rendelkező felhasználó nem található.
 *       500:
 *         description: Szerver oldali hiba.
 */
router.get('/:id', (req, res) => {
  const { id } = req.params;
  res.json({ id: parseInt(id), name: `Felhasználó ${id}` });
});

/**
 * @swagger
 * /users:
 *   post:
 *     summary: Új felhasználó létrehozása
 *     tags: [Felhasználók]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/NewUser'
 *     responses:
 *       201:
 *         description: A felhasználó sikeresen létrehozva.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       400:
 *         description: Érvénytelen bemeneti adatok.
 *       500:
 *         description: Szerver oldali hiba.
 */
router.post('/', (req, res) => {
  const newUser = { id: Math.floor(Math.random() * 1000) + 3, ...req.body };
  res.status(201).json(newUser);
});

/**
 * @swagger
 * /users/{id}:
 *   put:
 *     summary: Felhasználó frissítése azonosító alapján
 *     tags: [Felhasználók]
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: A frissítendő felhasználó egyedi azonosítója.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/NewUser' # Re-using NewUser schema for update
 *     responses:
 *       200:
 *         description: A felhasználó sikeresen frissítve.
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 *       400:
 *         description: Érvénytelen bemeneti adatok.
 *       404:
 *         description: A megadott azonosítóval rendelkező felhasználó nem található.
 *       500:
 *         description: Szerver oldali hiba.
 */
router.put('/:id', (req, res) => {
  const { id } = req.params;
  const updatedUser = { id: parseInt(id), ...req.body };
  res.status(200).json(updatedUser);
});

/**
 * @swagger
 * /users/{id}:
 *   delete:
 *     summary: Felhasználó törlése azonosító alapján
 *     tags: [Felhasználók]
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: A törlendő felhasználó egyedi azonosítója.
 *     responses:
 *       204:
 *         description: A felhasználó sikeresen törölve (No Content).
 *       404:
 *         description: A megadott azonosítóval rendelkező felhasználó nem található.
 *       500:
 *         description: Szerver oldali hiba.
 */
router.delete('/:id', (req, res) => {
  // Feltételezzük, hogy a felhasználó létezik és töröljük.
  res.status(204).send();
});


module.exports = router;
```

Most integráljuk ezt az útvonalat az `app.js` fájlba:

// app.js (kiegészítve)
// ...
const usersRouter = require('./routes/users'); // Importáljuk a users útvonalat
app.use('/users', usersRouter); // Használjuk az útvonalat
// ...

Fontos, hogy definiáljuk azokat a sémákat (modelleket), amelyekre a `User` és `NewUser` hivatkozik. Hozzunk létre egy `models` mappát és azon belül egy `user.js` fájlt:

mkdir models
touch models/user.js

Majd illesszük be a következő tartalmat a `models/user.js` fájlba:

// models/user.js
/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - name
 *       properties:
 *         id:
 *           type: integer
 *           format: int64
 *           description: A felhasználó egyedi azonosítója.
 *           example: 1
 *         name:
 *           type: string
 *           description: A felhasználó teljes neve.
 *           example: John Doe
 *         email:
 *           type: string
 *           format: email
 *           description: A felhasználó e-mail címe.
 *           example: [email protected]
 *     NewUser:
 *       type: object
 *       required:
 *         - name
 *         - email
 *       properties:
 *         name:
 *           type: string
 *           description: Az új felhasználó neve.
 *           example: Jane Smith
 *         email:
 *           type: string
 *           format: email
 *           description: Az új felhasználó e-mail címe.
 *           example: [email protected]
 */

Ne felejtsd el, hogy a `swaggerConfig.js` fájlban az `apis` tömbnek tartalmaznia kell a `models/*.js` bejegyzést, hogy a swagger-jsdoc feldolgozza ezeket a sémákat is!

A legfontosabb Swagger JSDoc annotációk magyarázata:

  • `@swagger`: Ez a fő tag, ami jelzi a swagger-jsdoc-nak, hogy a következő kommentblokk OpenAPI definíciókat tartalmaz.
  • `tags`: Az API végpontok csoportosítására szolgál. Ez segít rendszerezni a felületet a Swagger UI-ban.
  • `summary`: Egy rövid, egy soros leírás az adott végpontról vagy műveletről.
  • `description`: Részletesebb leírás, támogathatja a Markdown formázást.
  • `parameters`: A végponthoz tartozó paraméterek definiálására szolgál.
    • `in`: Hol található a paraméter (path, query, header, cookie).
    • `name`: A paraméter neve.
    • `schema`: A paraméter típusa (string, integer, boolean stb.).
    • `required`: Kötelező-e a paraméter (true/false).
    • `description`: A paraméter leírása.
  • `requestBody`: POST/PUT kérések esetén a kérés törzsének (payload) definiálására szolgál.
    • `required`: Kötelező-e a kérés törzse.
    • `content`: A kérés tartalmának típusa (pl. `application/json`) és sémája.
  • `responses`: A lehetséges HTTP válaszok (pl. 200, 201, 400, 404, 500) definiálása.
    • `description`: A válasz rövid leírása.
    • `content`: A válasz tartalmának típusa és sémája.
  • `components/schemas`: Lehetővé teszi, hogy újrafelhasználható sémákat (modelleket) definiáljunk az API-ban. Ez különösen hasznos, ha több végpont is ugyanazokat az adatstruktúrákat használja. A `$ref: '#/components/schemas/User'` segítségével hivatkozhatunk ezekre.
  • `security`: Definiálhatod az adott végponthoz szükséges autentikációt (pl. `bearerAuth` JWT token).

Most indítsd újra az Express.js szervered. Látni fogod, hogy a Swagger UI (`http://localhost:3000/api-docs`) most már szépen megjeleníti a "Felhasználók" csoportot az összes definiált végponttal és a hozzájuk tartozó dokumentációval! Kipróbálhatod őket a "Try it out" gombbal!

Tippek és bevált gyakorlatok a tökéletes API dokumentációhoz

A működő Swagger UI csak az első lépés. Íme néhány tipp, hogy a dokumentációd valóban kiváló minőségű legyen:

  1. Légy konzisztens: Használj egységes elnevezési konvenciókat és leírási stílust az egész dokumentációban.
  2. Légy részletes, de tömör: Ne írj regényt, de adj elegendő információt ahhoz, hogy bárki megértse a végpont működését.
  3. Használj példákat: Mind a `requestBody`, mind a `responses` esetében adj meg `example` értékeket a sémáidban. Ez drámaian megkönnyíti a fejlesztők dolgát.
  4. Definiáld az összes hibaválaszt: Ne csak a sikeres (2xx) válaszokat dokumentáld, hanem a lehetséges hibaüzeneteket (4xx, 5xx) is, beleértve a hibaüzenetek struktúráját is.
  5. Dokumentáld az autentikációt: Ha az API-d védett, egyértelműen írd le, hogyan kell autentikálni (pl. JWT token, API kulcs). Ezt a `securitySchemes` és `security` tagekkel teheted meg.
  6. Verziózás: Ha az API-d fejlődik, valószínűleg verzióznod kell. Ezt jelezd a `info.version` mezőben, és fontold meg az API útvonalak verziózását is (pl. `/v1/users`).
  7. Tartsd naprakészen: A swagger-jsdoc használatával ez viszonylag egyszerű, de fontos, hogy minden kódmódosítást kövessen a dokumentáció frissítése.
  8. Használj külső fájlokat (ha komplex az API): Ha az OpenAPI specifikáció túl nagyra nő, szétoszthatod több YAML vagy JSON fájlba, és hivatkozhatsz egymásra az `$ref` segítségével. A swagger-jsdoc továbbra is képes lesz ezeket összesíteni.

Miért éri meg a befektetett energia?

Egy jó minőségű API dokumentáció készítése elsőre időigényesnek tűnhet, de a hosszú távú előnyök messze felülmúlják a kezdeti befektetést. A csapatod produktívabb lesz, kevesebb hiba fog előfordulni, és az API-d sokkal felhasználóbarátabbá válik, mind a belső, mind a külső fejlesztők számára. Az Express.js és a Swagger párosa egy rendkívül hatékony és modern megoldást kínál erre a kihívásra.

Összefoglalás

Ebben a cikkben végigvezettünk azon, hogyan hozhatsz létre átfogó és interaktív API dokumentációt Express.js alkalmazásodhoz a Swagger (OpenAPI) és a hozzá tartozó eszközök, a swagger-jsdoc és a swagger-ui-express segítségével. Láthattad, hogyan kell beállítani a projektet, integrálni a Swagger UI-t, és hogyan kell dokumentálni az API végpontokat JSDoc kommentek segítségével. Ne feledd, egy jól dokumentált API egy boldog API, ami hosszú távon sikeresebb projektekhez vezet!

Most már minden tudás a kezedben van ahhoz, hogy te is elkezdhesd a professzionális API dokumentáció készítését! Jó kódolást és dokumentálást kívánok!

Kapcsolódó

Leave a Reply

Az e-mail címet nem tesszük közzé. A kötelező mezőket * karakterrel jelöltük