WisarWisar
Dasturlash kitobi/5-QISM — Nodejs15 daqiqa

5.23-bob: API hujjatlari — Swagger / OpenAPI

5-QISM — Node.js Backend · 23-mavzu (yakuniy)

1. Kirish va motivatsiya

5-QISMning yakuniy bobiga keldik. Backend'ni to'liq qurdik: server, REST, auth, validatsiya, fayl, real-time, navbat (5.1–5.22). Endi muhim, lekin ko'pincha e'tibordan chetda qoladigan mavzuni — API'ni hujjatlashni — o'rganamiz. API yozish — yarim ish; uni boshqalar qanday ishlatishini tushuntirish — ikkinchi yarmi.

Tasavvur qiling: siz backend yozdingiz (REST API — 5.7). Endi frontend dasturchi (11) undan foydalanishi kerak: qaysi endpoint'lar bor? Qaysi metod (GET/POST)? Qanday ma'lumot yuborish kerak? Javob qanday ko'rinishda? Qaysi status kodlar? Auth qanday? Bularning hammasini og'zaki yoki alohida hujjatda tushuntirish — sekin, xatoga moyil, eskirib qoladi. Yechim — avtomatik, interaktiv, kod bilan sinxron hujjat: Swagger / OpenAPI.

OpenAPI — REST API'ni tasvirlovchi standart (sanoat standarti). Swagger — shu standart asosida interaktiv hujjat (veb-sahifa) yaratuvchi vosita. Swagger UI orqali har bir endpoint ko'rinadi, va eng zo'ri — uni brauzerda to'g'ridan sinab ko'rish mumkin ("Try it out" tugmasi). Bu — jamoa ishini, frontend bilan hamkorlikni, va API'ni tushunishni keskin osonlashtiradi.

O'xshatish: API hujjati — qurilmaning foydalanuvchi qo'llanmasi (instruksiya). Telefon sotib olsangiz, qutida qo'llanma bor: qaysi tugma nima qiladi, qanday ulanadi, nima qilsa bo'ladi. Qo'llanmasiz qurilma — har tugmani sinab ko'rasiz (vaqt isrofi, xato). API hujjati ham shunday: frontend dasturchi "qaysi endpoint, qanday ma'lumot, qanday javob" ni o'qiydi — taxmin qilmaydi. Swagger — bu qo'llanmaning interaktiv versiyasi (o'qibgina qolmay, sinab ham ko'rasiz).

Nega muhim?

  • Jamoa ishi — frontend (11) va backend hamkorligi; har kim API'ni biladi.
  • Vaqt tejaydi — og'zaki tushuntirish, alohida hujjat yozish o'rniga.
  • Interaktiv test — brauzerda endpoint'ni sinab ko'rish (Postman'siz).
  • Standart — OpenAPI sanoat standarti; client generatsiya, validatsiya.

2. Nazariya — chuqur tushuntirish

2.1. API hujjati nima va nega kerak

API hujjati — API'dan qanday foydalanishni tushuntiruvchi ma'lumot:

text
  Har endpoint uchun:
  - Yo'l va metod (GET /api/products — 5.7)
  - Parametrlar (query, path, body — 5.6)
  - So'rov formati (qanday ma'lumot yuborish)
  - Javob formati (qanday qaytadi, status kodlar — 5.7)
  - Auth talabi (token kerakmi — 5.15)
  - Xato javoblari (400, 401, 404 — 5.10)

Muammo: qo'lda yozilgan hujjat eskirib qoladi (kod o'zgaradi, hujjat qolib ketadi). Yechim — kod bilan sinxron hujjat (kod o'zgarsa, hujjat ham — 2.4).

2.2. OpenAPI vs Swagger (farq)

text
  OpenAPI  — SPETSIFIKATSIYA (standart): API'ni tasvirlash qoidalari (JSON/YAML format)
             (avval "Swagger Specification" deb atalgan)
  Swagger  — VOSITALAR to'plami: OpenAPI asosida ishlaydigan asboblar
             - Swagger UI — interaktiv hujjat sahifasi 2.3-bob
             - Swagger Editor — spetsifikatsiya yozish
             - Swagger Codegen — koddan client generatsiya

Sodda qilib: OpenAPI — "til/standart" (API'ni qanday tasvirlash); Swagger — shu tilda yozilganni "ko'rsatuvchi/ishlatuvchi" asboblar. Ko'pincha ikkalasi bir ma'noda ishlatiladi. Biz OpenAPI formatida tasvirlaymiz, Swagger UI bilan ko'rsatamiz.

2.3. Swagger UI — interaktiv hujjat

Swagger UI — OpenAPI tavsifini chiroyli, interaktiv veb-sahifaga aylantiradi:

text
  /api-docs sahifasi:
  - Barcha endpoint'lar ro'yxati (guruhlangan)
  - Har birini ochib, tafsilotini ko'rish (parametr, javob)
  - "Try it out" — brauzerda TO'G'RIDAN sinab ko'rish (so'rov yuborish!)
  - Auth kiritish (token) — himoyalangan endpoint'larni sinash

"Try it out" — Swagger'ning eng kuchli tomoni: frontend dasturchi Postman'siz, kod yozmasdan, brauzerda endpoint'ni sinab ko'radi (real so'rov, real javob). Hujjat — "tirik".

2.4. Hujjatni qanday yaratish (ikki yondashuv)

text
  1. Kod ichida izoh (annotation) — swagger-jsdoc
     Route yoniga JSDoc izoh yozasiz (@openapi)  avtomatik OpenAPI hosil bo'ladi
      Kod bilan yonma-yon (sinxron);  izohlar ko'p joy oladi

  2. Alohida spetsifikatsiya (YAML/JSON) yoki kod-first (NestJS — 8.10)
     Alohida fayl yoki dekorator  spetsifikatsiya

Express'da eng keng tarqalgan — swagger-jsdoc (izoh) + swagger-ui-express (ko'rsatish). NestJS'da 8.10-bob — dekorator (@ApiProperty — avtomatik). Bu bobda Express yondashuvini o'rganamiz.

2.5. O'rnatish (swagger-jsdoc + swagger-ui-express)

bash
npm install swagger-jsdoc swagger-ui-express          # (5.2)
text
  swagger-jsdoc       — kod izohlaridan (@openapi) OpenAPI obyekti yasaydi
  swagger-ui-express  — shu obyektni /api-docs sahifasida ko'rsatadi

2.6. Asosiy sozlash (definition)

js
import swaggerJsdoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const spec = swaggerJsdoc({
  definition: {
    openapi: "3.0.0",                                   // OpenAPI versiyasi
    info: { title: "Mana API", version: "1.0.0", description: "..." },
    servers: [{ url: "http://localhost:3000" }],
  },
  apis: ["./routes/*.js"],                              // izoh qidiriladigan fayllar (2.7)
});

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));   // /api-docs sahifasi (2.3)

2.7. Endpoint'ni hujjatlash (JSDoc izoh — 2.4)

Route yoniga @openapi izohi (swagger-jsdoc):

js
/**
 * @openapi
 * /api/products:
 *   get:
 *     summary: Barcha mahsulotlar
 *     tags: [Products]
 *     responses:
 *       200:
 *         description: Mahsulotlar ro'yxati
 */
app.get("/api/products", getProducts);

Izoh YAML formatida (OpenAPI). swagger-jsdoc uni o'qib, OpenAPI obyektiga qo'shadi. tags — endpoint'larni guruhlaydi (Swagger UI'da bo'limlar).

2.8. Komponentlar — qayta ishlatiladigan schema (DRY)

Ma'lumot modellarini (Product, User) bir marta ta'riflab, qayta ishlatish (best practices):

js
/**
 * @openapi
 * components:
 *   schemas:
 *     Product:
 *       type: object
 *       required: [nom, narx]
 *       properties:
 *         id: { type: string }
 *         nom: { type: string, example: "Olma" }
 *         narx: { type: number, example: 12000 }
 */

Keyin endpoint'larda $ref: '#/components/schemas/Product' bilan ishora qilasiz (takrorlamasdan — DRY). required — majburiy maydonlar (5.9: validatsiya bilan mos); example — namuna qiymat.

2.9. So'rov body va parametrlarni hujjatlash

text
  parameters    — path (/:id), query (?page=) — 5.6
  requestBody   — POST/PUT body (yuboriladigan ma'lumot)
  responses     — status kodlar va javob formati (5.7)

Bu — API'ning "shartnoma"si: frontend nima yuborishi va nima olishi aniq yoziladi. Validatsiya 5.9-bob bilan mos bo'lishi kerak (hujjat va haqiqat bir xil).

2.10. Auth'ni hujjatlash (security — 5.15)

Himoyalangan endpoint'lar (token kerak — 5.15) Swagger'da belgilanadi:

js
/**
 * @openapi
 * components:
 *   securitySchemes:
 *     bearerAuth:
 *       type: http
 *       scheme: bearer
 *       bearerFormat: JWT
 */
// Endpoint'da: security: [{ bearerAuth: [] }]

Bu — Swagger UI'da "Authorize" tugmasini chiqaradi: token kiritasiz, keyin himoyalangan endpoint'larni sinab ko'rasiz ("Try it out" auth bilan). Frontend uchun — qaysi endpoint auth talab qilishini ko'rsatadi.

2.11. Status kodlar va xatolarni hujjatlash (5.7, 5.10)

text
  responses:
    200 — muvaffaqiyat (javob schema bilan)
    201 — yaratildi 5.7-bob
    400 — validatsiya xatosi 5.9-bob
    401 — avtorizatsiya kerak 5.15-bob
    403 — ruxsat yo'q 5.17-bob
    404 — topilmadi
    500 — server xatosi (5.10)

Har endpoint mumkin bo'lgan barcha javoblarni hujjatlashi kerak (faqat 200 emas). Frontend xatolarni qanday boshqarishni shu yerdan biladi.

2.12. Hujjat va kod sinxronligi (eng muhim)

Eng katta xavf: hujjat eskirib qolishi (kod o'zgaradi, izoh qolib ketadi):

text
   Izoh route yoniga (yonma-yon — unutilmaydi — 2.4)
   Validatsiya schema (Zod — 5.9)  OpenAPI generatsiya (zod-to-openapi) — bitta manba!
   Code review'da hujjatni ham tekshiring (15.2)

Eng yaxshi yechim: validatsiya schema'sidan (Zod — 5.9) OpenAPI'ni avtomatik generatsiya qilish (zod-to-openapi) — bitta manba (schema), ham validatsiya, ham hujjat. Yoki NestJS'da 8.10-bob dekorator — DTO'dan avtomatik.

2.13. Production'da Swagger (xavfsizlik — 14)

Swagger UI — API tuzilishini oshkor qiladi (endpoint'lar, ma'lumot). Production'da ehtiyot (14):

text
   Public API — Swagger ochiq mayli (maqsad — ishlatish)
   Ichki/maxfiy API — Swagger'ni himoyalang (auth) yoki production'da o'chiring
   Maxfiy ma'lumotni example'da ko'rsatmang (parol, kalit — 14)

Kichik/ichki loyihada Swagger'ni production'da o'chirish yoki parol bilan himoyalash mumkin. Public API — ochiq (foydalanuvchilar uchun).

2.14. Boshqa hujjatlash vositalari (qisqacha)

text
  Postman        — so'rovlar to'plami; hujjat + test (kollektsiya ulashish)
  Insomnia       — Postman muqobili
  Redoc          — Swagger UI muqobili (chiroyli, faqat ko'rish)
  Scalar         — zamonaviy OpenAPI UI
  NestJS Swagger  — dekorator asosida avtomatik 8.10-bob
  openapi-typescript / orval — OpenAPI'dan TS tip va klient avtomatik (frontend — 11)

OpenAPI standart — bir marta yozsangiz, har vositada ishlaydi (Swagger UI, Redoc, Postman import). Standart — bog'lanmaslik (vendor lock-in yo'q).

3. Sintaksis — tez ma'lumotnoma

js
import swaggerJsdoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const spec = swaggerJsdoc({
  definition: { openapi: "3.0.0", info: { title, version }, servers: [...] },
  apis: ["./routes/*.js"],                              // izoh fayllari (2.6)
});
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));   // (2.3)

// Izoh (route yoniga — 2.7):
/**
 * @openapi
 * /api/x:
 *   get:
 *     summary: ...
 *     responses: { 200: { description: OK } }
 */

4. Batafsil kod namunalari

Misol 1 — Asosiy Swagger sozlash (2.6)

js
// config/swagger.js
import swaggerJsdoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const spec = swaggerJsdoc({
  definition: {
    openapi: "3.0.0",
    info: {
      title: "Mana Do'kon API",
      version: "1.0.0",
      description: "E-commerce backend API hujjati",
    },
    servers: [
      { url: "http://localhost:3000", description: "Dev" },
      { url: "https://api.mana.uz", description: "Production" },
    ],
  },
  apis: ["./routes/*.js"],                              // izoh qidiriladigan fayllar (2.6)
});

export const swaggerSetup = (app) => {
  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));   // (2.3)
  console.log(" Swagger: http://localhost:3000/api-docs");
};

// app.js: import { swaggerSetup } from "./config/swagger.js"; swaggerSetup(app);

Misol 2 — GET endpoint hujjati (2.7)

js
/**
 * @openapi
 * /api/products:
 *   get:
 *     summary: Barcha mahsulotlarni olish
 *     tags: [Products]
 *     parameters:
 *       - in: query
 *         name: page
 *         schema: { type: integer, default: 1 }
 *         description: Sahifa raqami
 *       - in: query
 *         name: limit
 *         schema: { type: integer, default: 20 }
 *     responses:
 *       200:
 *         description: Mahsulotlar ro'yxati
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items: { $ref: '#/components/schemas/Product' }
 */
router.get("/products", getProducts);

Misol 3 — Komponent schema (qayta ishlatiladigan — 2.8)

js
/**
 * @openapi
 * components:
 *   schemas:
 *     Product:
 *       type: object
 *       required: [nom, narx]
 *       properties:
 *         id:
 *           type: string
 *           example: "65a1b2c3d4e5f6"
 *         nom:
 *           type: string
 *           example: "Olma"
 *         narx:
 *           type: number
 *           example: 12000
 *         mavjud:
 *           type: boolean
 *           example: true
 *     Error:
 *       type: object
 *       properties:
 *         success: { type: boolean, example: false }
 *         error: { type: object }
 */

Misol 4 — POST endpoint (body bilan — 2.9)

js
/**
 * @openapi
 * /api/products:
 *   post:
 *     summary: Yangi mahsulot qo'shish
 *     tags: [Products]
 *     security:
 *       - bearerAuth: []          # auth kerak (2.10, 5.15)
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [nom, narx]
 *             properties:
 *               nom: { type: string, example: "Banan" }
 *               narx: { type: number, example: 18000 }
 *     responses:
 *       201:
 *         description: Yaratildi
 *         content:
 *           application/json:
 *             schema: { $ref: '#/components/schemas/Product' }
 *       400:
 *         description: Validatsiya xatosi
 *         content:
 *           application/json:
 *             schema: { $ref: '#/components/schemas/Error' }
 *       401:
 *         description: Avtorizatsiya kerak
 */
router.post("/products", auth, roleRequired("admin"), createProduct);   // (5.15, 5.17)

Misol 5 — Auth (security scheme — 2.10)

js
/**
 * @openapi
 * components:
 *   securitySchemes:
 *     bearerAuth:
 *       type: http
 *       scheme: bearer
 *       bearerFormat: JWT          # 5.15-bob
 */

// definition'ga global security (yoki har endpoint'da):
const spec = swaggerJsdoc({
  definition: {
    openapi: "3.0.0",
    info: { title: "Mana API", version: "1.0.0" },
    components: {
      securitySchemes: {
        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
      },
    },
  },
  apis: ["./routes/*.js"],
});
// Swagger UI'da "Authorize" tugmasi chiqadi — token kiritib, sinash (2.10)

Misol 6 — Path param va to'liq CRUD (2.9, 5.7)

js
/**
 * @openapi
 * /api/products/{id}:
 *   get:
 *     summary: Bitta mahsulot
 *     tags: [Products]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema: { type: string }
 *     responses:
 *       200:
 *         description: Mahsulot topildi
 *         content:
 *           application/json:
 *             schema: { $ref: '#/components/schemas/Product' }
 *       404:
 *         description: Topilmadi
 *   delete:
 *     summary: Mahsulotni o'chirish
 *     tags: [Products]
 *     security: [{ bearerAuth: [] }]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema: { type: string }
 *     responses:
 *       204: { description: O'chirildi }
 *       403: { description: Ruxsat yo'q }
 *       404: { description: Topilmadi }
 */
router.get("/products/:id", getProduct);
router.delete("/products/:id", auth, roleRequired("admin"), deleteProduct);

Misol 7 — Zod schema'dan avtomatik OpenAPI (sinxronlik — 2.12)

js
// zod-to-openapi — validatsiya va hujjat BITTA manbadan (2.12, 5.9)
import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
extendZodWithOpenApi(z);

// Schema — ham validatsiya 5.9-bob, ham hujjat (bitta manba!)
const ProductSchema = z.object({
  nom: z.string().openapi({ example: "Olma" }),
  narx: z.number().positive().openapi({ example: 12000 }),
}).openapi("Product");

// Bu schema'dan: validatsiya 5.9-bob VA OpenAPI hujjati avtomatik generatsiya
//  kod o'zgarsa, ikkalasi ham yangilanadi (eskirmaydi — 2.12)

Misol 8 — Production'da himoya (2.13, 14)

js
import basicAuth from "express-basic-auth";

// Swagger UI'ni production'da parol bilan himoyalash (2.13, 14)
if (config.isProd) {
  app.use("/api-docs", basicAuth({
    users: { admin: config.swaggerPassword },           // .env (5.8)
    challenge: true,
  }));
}
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));
// Ichki API — production'da Swagger faqat parol bilan (14)

5. To'g'ri va noto'g'ri holatlar

1) Hujjatsiz API

text
 frontend taxmin qiladi/og'zaki so'raydi (sekin, xato — 2.1)
 Swagger — har endpoint hujjatlangan, interaktiv

2) Hujjat kod bilan sinxron emas

text
 kod o'zgardi, izoh eski (frontend noto'g'ri ma'lumot — 2.12)
 izoh yonma-yon; Zod'dan avtomatik (Misol 7)

3) Faqat 200 javobni hujjatlash

text
 xato javoblar (400/401/404) yo'q (frontend xatoni bilmaydi — 2.11)
 barcha mumkin javoblarni hujjatlang

4) Maxfiy ma'lumotni example'da

js
//  haqiqiy token/parol example'da (14, 2.13)
example: "Bearer eyJhbGc...real-token"

//  namunaviy/soxta
example: "Bearer <token>"

5) Production'da ichki Swagger ochiq

text
 maxfiy API tuzilishi hammaga ochiq (14, 2.13)
 auth bilan himoyalang yoki o'chiring

6. Keng tarqalgan xatolar va yechimlari

Xato 1 — Swagger UI bo'sh (endpoint'lar yo'q)

Sababi: apis yo'li noto'g'ri (izoh fayllari topilmadi — 2.6). Yechimi: apis: ["./routes/*.js"] to'g'ri yo'l; izohlar @openapi tag bilan.

Xato 2 — Izoh ko'rinmaydi

Sababi: YAML formati xato (bo'shliq/tab — YAML bo'shliqqa sezgir). Yechimi: izoh formatini tekshiring (bir xil bo'shliq); Swagger Editor'da sinab ko'ring.

Xato 3 — $ref ishlamaydi

Sababi: komponent ta'riflanmagan yoki yo'l xato 2.8-bob. Yechimi: components/schemas ta'riflangan; $ref: '#/components/schemas/Product' to'g'ri.

Xato 4 — "Try it out" CORS xatosi

Sababi: Swagger boshqa origin'dan so'rov yuboradi 5.20-bob. Yechimi: CORS sozlang; servers to'g'ri URL.

Xato 5 — Auth "Try it out"da ishlamaydi

Sababi: securityScheme yo'q yoki endpoint'da security belgilanmagan 2.10-bob. Yechimi: securitySchemes ta'riflang; endpoint'da security.

Xato 6 — Hujjat haqiqatdan farq qiladi

Sababi: kod o'zgardi, izoh qoldi 2.12-bob. Yechimi: izohni yangilang; Zod'dan generatsiya (Misol 7); code review 15.2-bob.

7. Integratsiya — bu mavzu stack'ning qayerida uchraydi

  • REST 5.7-bob: Swagger REST API'ni hujjatlaydi (endpoint, status).
  • Express 5.6-bob: swagger-ui-express middleware.
  • Validatsiya 5.9-bob: schema hujjat bilan mos; Zod'dan generatsiya.
  • Auth 5.15-bob: security scheme (JWT).
  • RBAC 5.17-bob: qaysi endpoint qaysi rol (hujjatda).
  • Error handling 5.10-bob: xato javoblari hujjatda.
  • Xavfsizlik (14): production'da Swagger himoyasi.
  • Frontend (11): API'ni Swagger'dan o'rganadi; client generatsiya.
  • NestJS 8.10-bob: @nestjs/swagger — dekorator (DTO'dan avtomatik).
  • Kasbiy (15): code review, jamoa hamkorligi.

8. Eng yaxshi amaliyotlar (best practices)

  • Har API'ni hujjatlang (Swagger — jamoa/frontend uchun — 2.1).
  • Izoh route yoniga (yonma-yon — sinxron — 2.4, 2.12).
  • Komponent schema (qayta ishlatish — $ref — DRY — 2.8).
  • Barcha javoblarni hujjatlang (200 + 400/401/404/500 — 2.11).
  • Auth'ni belgilang (security scheme — "Authorize" — 2.10).
  • Hujjat-kod sinxronligi (Zod'dan generatsiya — bitta manba — 2.12, Misol 7).
  • Maxfiy ma'lumotni example'da ko'rsatmang (14, 2.13).
  • Production'da ichki Swagger'ni himoyalang (auth/o'chir — 2.13, 14).
  • Tag bilan guruhlang (Products, Users, Auth — 2.7).
  • OpenAPI standart (Redoc/Postman/client'ga ham — 2.14).

9. Amaliy loyiha: "To'liq API Hujjati (Swagger)"

API hujjatlashni professional darajada mustahkamlash.

Maqsad

Swagger/OpenAPI bilan to'liq, interaktiv API hujjatini qurish: barcha endpoint'lar, schema'lar, auth, xato javoblari — kod bilan sinxron.

Talablar (requirements)

  1. Sozlash: swagger-jsdoc + swagger-ui-express; /api-docs sahifasi (Misol 1, 2.6).
  2. Komponent schema'lar: Product, User, Error — qayta ishlatiladigan ($ref — Misol 3, 2.8).
  3. CRUD endpoint'lar: GET (list+query), GET/:id, POST (body), PATCH, DELETE — hujjatlangan (Misol 2, 4, 6).
  4. Auth: bearerAuth security scheme; himoyalangan endpoint'larda security (Misol 5, 2.10).
  5. Barcha javoblar: 200/201/400/401/403/404 (Misol 4, 2.11).
  6. Tag bilan guruhlash: Products, Auth, Users 2.7-bob.
  7. "Try it out": brauzerda endpoint'larni (auth bilan) sinash 2.3-bob.
  8. Hujjat-kod sinxronligi: validatsiya 5.9-bob bilan mos 2.12-bob.
  9. (Bonus) Zod'dan avtomatik: zod-to-openapi (Misol 7, 2.12).
  10. (Bonus) Production himoyasi: Swagger'ni parol bilan (Misol 8, 2.13).

Maslahatlar (hint)

  • apis: ["./routes/*.js"] — izoh yo'li (2.6, 1-xato).
  • Izoh @openapi tag, YAML format (bo'shliqqa sezgir — 2-xato).
  • Schema: components/schemas + $ref (2.8, 3-xato).
  • Auth: securitySchemes + security: [{ bearerAuth: [] }] 2.10-bob.
  • Barcha status kodlar (2.11, 3-holat).
  • Production: basic-auth 2.13-bob.

"Tayyor" mezonlari (acceptance criteria)

  • /api-docs sahifasi ochiladi, endpoint'lar ko'rinadi.
  • Komponent schema'lar ($ref bilan) ishlaydi.
  • Barcha CRUD endpoint'lar hujjatlangan.
  • Auth (Authorize tugmasi) ishlaydi.
  • Barcha javoblar (200+xatolar) hujjatlangan.
  • Tag bilan guruhlangan.
  • "Try it out" bilan sinab ko'rish mumkin.
  • Hujjat haqiqiy API bilan mos.
  • (Bonus) Zod'dan generatsiya / production himoyasi.

Yechim kodi ataylab berilmagan — bu loyihani o'zingiz yozib ko'ring.

10. Xulosa va keyingi QISMga ko'prik

Bu bobda API'ni professional hujjatlashni — Swagger / OpenAPI — o'rgandik:

  • API hujjati zarur (jamoa/frontend — 2.1); OpenAPI (standart) vs Swagger (vositalar — 2.2); Swagger UI (interaktiv, "Try it out" — 2.3).
  • swagger-jsdoc + swagger-ui-express (izohdan — 2.4, 2.5); endpoint hujjati 2.7-bob; komponent schema ($ref — DRY — 2.8).
  • Body/parametr/javob (2.9, 2.11); auth (security scheme — 2.10); hujjat-kod sinxronligi (Zod'dan — 2.12).
  • Production himoyasi (ichki Swagger — 14, 2.13); boshqa vositalar (Redoc/Postman — 2.14).

5-QISM (Node.js Backend) TUGADI! Biz Node.js asoslaridan (event loop, core modullar — 5.1-5.4) boshlab, HTTP/Express (5.5-5.6), REST/validatsiya/error (5.7-5.10), fayl/logger/real-time/bot (5.11-5.14), auth/RBAC/OTP/email (5.15-5.19), xavfsizlik/Redis/navbat/Swagger (5.20-5.23) — to'liq, production-darajali backend qurishni o'rgandik.

Keyingi — 6-QISM: Ma'lumotlar bazasi (Database). Backend'ning yuragi — ma'lumotni saqlash. Bu qismda: DB asoslari (SQL vs NoSQL), MongoDB + Mongoose (schema, CRUD, aggregation, indekslar, relations), SQL (PostgreSQL/MySQL, JOIN, normalizatsiya, tranzaksiya), va ORMlar (Sequelize, Prisma, TypeORM) — chuqur o'rganamiz. Hozirgacha ma'lumotni DB'ga "saqladik" deb o'tdik; endi DB'ning o'zini ustasi bo'lamiz.

Foydalanilgan rasmiy/ishonchli manbalar

  • swagger.io / OpenAPI Specification 3.0; swagger-jsdoc, swagger-ui-express (npm)
  • DEV/LogRocket — Documenting Express API with Swagger 2026 (jsdoc, components, auth)
  • @asteasolutions/zod-to-openapi — Zod schema OpenAPI (sinxronlik)

Izohlar (0)

Izoh yozish uchun kiring.

  • Hozircha izoh yo'q. Birinchi bo'ling!
5.23-bob: API hujjatlari — Swagger / OpenAPI — Wisar