API hujjatlari: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - haqiqat manbai: shartnoma → SDK → moq → testlar → portal.
Swagger UI/Redoc - o’qiladigan vitrin; Postman - ijro etiladigan ssenariylar.
Biz linterlar, breaking-checks, misollar va xato sxemalarini tikamiz, SDK va Mock-serverlarni yaratamiz, «Sunset» va versiyaga ega dev-portal nashr etamiz.

1) Maqsad va prinsiplar

Bitta kontrakt (OpenAPI). Qolgan hamma narsa ishlab chiqariladi.
Hujjatlar bajarilishi mumkin: so’rovlar Postman/CLI da sinovdan o’tkaziladi.
Andoza xavfsizlik: xato, limit, autentifikatsiya sxemalari.
Version va hayot sikli:’v1 ’/’ v2’, Deprecation/Sunset, changelog.

2) OpenAPI tuzilishi (minimal skelet)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• schemas/responses/parameters/requestBodies’components’ga joylashtiring.
• securitySchemes (OAuth2/JWT/HMAC) ni’paths ’/’ global’darajasida tasvirlang.

3) Xatolar standarti va meta ma’lumotlar

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

Har doim 429 (rate limit), 401/403 va’X-RateLimit-’,’Retry-After’sarlavhalarini hujjatlashtiring.

4) Misollar: request/response, curl va SDK

Har bir endpoint uchun: minimal va kengaytirilgan misol.
OpenAPI dan curl va snippet kodlarini (JS/Python/Go) yarating; qo’llaringiz bilan yozmang.
Haqiqiy qiymatlarni qo’llang: UUID, ISO-sana, «minor» (cents).

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI/Redoc - qanday nashr etish kerak

1. Swagger UI (interaktiv, try-it-out),

2. Redoc (o’qish mumkin bo’lgan uzun sahifalar).

Qorong’u mavzu, qidiruv, versiya selektori (’v1’,’v2’), Deprecation bannerini kiriting.

Prod-domen uchun «Try it out» ni yashiring, ruxsat bering sandbox.

6) Postman-kolleksiyalar: jonli stsenariylar

OpenAPI toʻplamini avtomatik ishlab chiqing va muhit oʻzgaruvchilarini qoʻllab-quvvatlang (’{{baseUrl}}’,’{{accessToken}}’).
Pretest (token olish) va post-testlarni (assert maqomi/sxemalari) qoʻshing.
Quyidagi jildlarga ajrating: Auth, Payments, Payouts, Webhooks.
Muhim yoʻnalishlar uchun monitorlarni eksport qiling.

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) Moki va sandbox

Mock-serverni OpenAPI’dan yarating.
Mok cheklovlarini belgilang: idempotentlik, kechikishlar, tasodifiy xatolar (UAT uchun).
Sandbox vs prod farqlarini (limitlar, maʼlumotlar, kechikishlar) hujjatlashtiring.

8) SDK avtogeneratsiyasi

OpenAPI dan rasmiy SDK (TypeScript, Python, Go) yarating.
SDK = SemVer reliz siyosati, API versiyasiga mapping.
README SDKda: autentifikatsiya, retraj, idempotentlik, 429/Retry-After qayta ishlash.

9) Linting, sinishlarni tekshirish va CI

Linterlar: spectral (uslublar/anti-patternlar), openapi-diff (breaking-checks).

• sxema validatori,
• linter,
• contract tests vs mok-server,
• Swagger/Redoc/kolleksiyalarini yig’ish,
• portalga e’lon qilish (staging → prod),
• Deprecation/Sunset haqida ogohlantirish.

10) Versiyalash, Deprecation, Sunset

URI (’/v1’) va’info’dagi versiya. version`.
Eskirgan bayroqlar:’Deprecation: true’,’Sunset: <RFC1123 date>’,’Link: <changelog>’sarlavhalari.
Portalda - banner va taymer o’chirilgunga qadar; v1 uchun Postman-kolleksiyalari muzlatilgan (faqat bagfiklar).

11) Dokdagi xavfsizlik va maxfiylik

Sirlarni, ichki URLlarni, haqiqiy PAN/PIIlarni chop etmang.
Sezgir maydonlar uchun - kamuflyaj va o’rindiqlar.
Swagger «Try it out» → faqat rate-limits bilan sandbox.
OAuth2/OIDC, HMAC (vebxuklar uchun) va mTLS (agar kerak boʻlsa) ni aniq tasvirlang.

12) Stayl-gayd kontraktlari

Resurslar koʻplikda: ’/payments’, ’/payouts’.
Identifikatorlari:’pay _’,’po _’, UUIDv4 yoki ksuid.
Sana - UTC ISO-8601; pul -’amount _ minor + currency’.
Paginatsiya - cursor-based (’? cursor = & limit =’), barqaror saralash.
Mutatsiyalar uchun idempotentlik - «Idempotency-Key».
Roʻyxatlar uchun barqaror’meta’va’links’obʼekti.

13) Dokdagi «Webhooks» bo’limi

Tadbir konvertiga, HMAC imzolariga, vaqt oynasiga, retrajlarga, javob kodlariga ega bo’lgan alohida bo’lim.
Hodisa tanalari namunalari va imzoni lokal tekshirish uchun Postman toʻplami.
Replay/DLQ endpointlari va UAT chek varaqasi.

14) Dev-portal: rollar va nashr etish

Bo’limlar: Sharh, Ish boshlash, Autentifikatsiya, Endpoints, Misollar, Vebxuki, SDK, Cheklovlar, Changelog.
Rollar: API Steward (standartlar), Domain Owner (kontent), Tech Writer (tahrir), DevRel (portal/hamjamiyat).
Ficha: sxemalar bo’yicha qidirish, sampllarni ko’chirish, «so’rovni yig’ish» → Postman.

15) Chek-varaqlar

• OpenAPI validen; xatosiz linter.
• Misollar 200/4xx/429/5xx ni qamrab oladi.
• Xavfsizlik: auth sxemalari tasvirlangan, hech qanday sir yo’q.
• Swagger/Redoc va Postman (prod/sandbox) yaratilgan.
• SDK tomonidan yaratilgan va nashr etilgan.
• Changelog va versiya selektori yangilandi.

• Deprecation/Sunset sarlavhalari kiritilgan.
• Portalda banner, sheriklarga xatlar.
• Eskirgan qo’ng’iroqlar ko’rsatkichlari maqsadli darajaga tushadi.

16) Anti-patternlar

Haqiqat manbalari (wiki ≠ OpenAPI).
Postman’da ishga tushirilmagan «koʻzga koʻrish» misollari.
Xatolarning yagona formati mavjud emas.
URI/domen oʻrniga «query-parametrda» versiyasi.
Swagger prodga kirish va limitsiz.
Kelishilmagan paginatsiya va autentifikatsiya sxemalari.

17) Avtomatlashtirish mini-snippetlari

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) Mahalliylashtirish va foydalanish

Alohida’info. description_<lang>' yoki ikkita portal yig’ilishi (EN/RU).
Glossariyadagi atamalar (KYC/AML, payout, idempotency).
Kontrast, klaviatura navigatsiyasi, qorong’u mavzu.

Xulosa

Hujjatlar konveyerini yigʻing: yagona OpenAPI-kontrakt → linterlar va breaking-checks → Swagger/Redoc vitrinalar → Postman kolleksiyalari va mok-server → SDK → dev-portal version va Sunset. Muntazam misollar, xatolarning yagona formati va qat’iy autentifikatsiya hujjatlarni «javondagi PDF» dan integratsiyaning ishchi vositasiga aylantiradi, hamkorlarni tezlashtiradi va qo’llab-quvvatlash narxini pasaytiradi.