API sənədləri: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - həqiqət mənbəyi: müqavilə → SDK → moki → testlər → portal.
Swagger UI/Redoc - oxunan vitrin; Postman - ssenarilər.
Biz linterlər, breaking-checks, nümunələr və səhv sxemləri tikirik, SDK və Mock-serverləri generasiya edirik, versiya və «Sunset» ilə qız portalı dərc edirik.

1) Məqsədlər və prinsiplər

Müqavilə bir (OpenAPI). Qalan hər şey yaradılır.
Sənədləşmə: sorğu nümunələri Postman/CLI-də sınaqdan keçirilir.
Default təhlükəsizlik: səhv sxemləri, limitlər, autentifikasiya.
Version və həyat dövrü: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) OpenAPI strukturu (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-i 'components' -ə yerləşdirin.
• securitySchemes (OAuth2/JWT/HMAC) təsvir edin və 'paths '/' global' səviyyəsində tətbiq edin.

3) Səhv və meta məlumat standartı

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 }

Həmişə 429 (rate limit), 401/403 və 'X-RateLimit-', 'Retry-After' başlıqlarını sənədləşdirin.

4) Nümunələr: request/response, curl və SDK

Hər bir end nöqtəsi üçün: minimal və genişləndirilmiş nümunə.
OpenAPI-dən curl və kod snippet (JS/Python/Go) yaradın; əllərinizlə yazmayın.
Real dəyərləri tətbiq edin: UUID, ISO tarixi, «minor» (cents) məbləğləri.

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 - necə dərc etmək olar

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

2. Redoc (oxunaqlı uzun səhifələr).

Daxil edin: qaranlıq mövzu, axtarış, versiya seçicisi ('v1', 'v2'), Deprecation banner.

Prod-domen üçün «Try it out» gizlətmək, sandbox icazə.

6) Postman kolleksiyaları: canlı ssenarilər

OpenAPI-dən kolleksiyanı avtomatik yaradın və mühit dəyişənlərini dəstəkləyin ('{{baseUrl}}', '{{accessToken}}').
Prestes (token alınması) və post-testlər (assert status/sxemlər) əlavə edin.
Qovluqlara bölün: Auth, Payments, Payouts, Webhooks.
Kritik marşrutlar üçün monitorları (cədvələ görə) ixrac edin.

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 və Sandbox

OpenAPI-dən mock serverini yaradın (nümunələrə görə/' example '/' examples ').
Mok məhdudiyyətlərini qeyd edin: idempotentlik, gecikmələr, təsadüfi səhvlər (UAT üçün).
Sandbox vs prod fərqlərini sənədləşdirin (limitlər, məlumatlar, gecikmələr).

8) SDK avtogenerasiyası

OpenAPI-dən rəsmi SDK (TypeScript, Python, Go) yaradın.
SDK = SemVer buraxılış siyasəti, API versiyası üçün mapping.
README SDK-da: autentifikasiya, retraj, idempotentlik, 429/Retry-After emalı.

9) Linting, sındırma yoxlama və CI

Linters: spectral (stillər/anti-nümunələr), openapi-diff (breaking-checks).

• sxem validator,
• linter,
• mok server qarşı contract tests,
• montaj Swagger/Redoc/kolleksiyaları,
• portalda nəşr (staging → prod),
• Deprecation/Sunset haqqında xəbərdarlıq.

10) Version, Deprecation, Sunset

URI ('/v1 ') və' info 'versiyası. version`.
Köhnəlmiş bayraqlar: başlıqlar 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
Portalda - bağlanana qədər banner və taymer; v1 üçün Postman kolleksiyaları dondurulub (yalnız bagficks).

11) Dock təhlükəsizlik və məxfilik

Sirləri, daxili URL-ləri, real PAN/PII-ləri dərc etməyin.
Həssas sahələr üçün - maskalanma və kilidləmə nümunələri.
Swagger «Try it out» → rate-limits ilə yalnız sandbox.
OAuth2/OIDC, HMAC (vebhook) və mTLS (lazım olduqda) dəqiq təsvir edin.

12) Style-Hyde müqavilələri

Cəm resursları: '/payments ', '/payouts'.
ID: 'pay _', 'po _', UUIDv4 və ya ksuid.
Tarixlər - UTC ISO-8601; pul - 'amount _ minor + currency'.
Paginasiya - cursor-based ('? cursor = & limit ='), sabit çeşidləmə.
İdempotentlik - mutasiyalar üçün «Idempotency-Key».
Siyahılar üçün sabit 'meta' və 'links' obyekti.

13) Dokda «Webhooks» bölməsi

Hadisə zərfi, HMAC imzaları, vaxt pəncərəsi, retrajlar, cavab kodları ilə ayrıca bölmə.
Hadisə cisimlərinin nümunələri və yerli imza yoxlaması üçün Postman kolleksiyası.
replay/DLQ end-point və UAT çek siyahısı.

14) Dev portalı: rollar və nəşr

Bölmələr: Baxış, Başlanğıc, Autentifikasiya, Son nöqtələr, Nümunələr, Vebhuki, SDK, Məhdudiyyətlər, Changelog.
Rollar: API Steward (standartlar), Domain Owner (məzmun), Tech Writer (redaktə), DevRel (portal/icma).
Ficha: sxem sahələrinə görə axtarış, nümunələrin kopyalanması, «sorğu toplamaq» → Postman.

15) Çek vərəqləri

• OpenAPI validen; xətasız linter.
• Nümunələr 200/4xx/429/5xx əhatə edir.
• Təhlükəsizlik: auth sxemləri təsvir, heç bir sirr.
• Swagger/Redoc və Postman (prod/sandbox) tərəfindən yaradılmışdır.
• SDK tərəfindən yaradılıb və nəşr olunub.
• Changelog və versiya seçicisi yeniləndi.

• Deprecation/Sunset başlıqları daxildir.
• Portalda banner, tərəfdaşlara məktublar.
• Köhnəlmiş versiyanın çağırış göstəriciləri hədəf səviyyəsinə düşür.

16) Anti-nümunələr

Həqiqətin təkrarlanan mənbələri (wiki ≠ OpenAPI).
Postman başlamadan «göz» nümunələri.
Vahid səhv formatının olmaması.
URI/domen əvəzinə «query-parametrdə» versiyası.
Qida və limitsiz giriş Swagger.
Razılaşdırılmamış paginasiya və autentifikasiya sxemləri.

17) Mini avtomatlaşdırma snippet

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) Lokalizasiya və əlçatanlıq

Ayrı-ayrı 'info. description_<lang>' və ya iki portal montajı (EN/RU).
Sözlükdəki terminlər (KYC/AML, payout, idempotency).
Kontrast, klaviatura naviqasiyası, qaranlıq mövzu.

Xülasə

Sənədlərin konveyerini toplayın: vahid OpenAPI-müqavilə → linterlər və breaking-checks → Swagger/Redoc vitrinləri → Postman kolleksiyaları və mok-server → SDK → Version və Sunset ilə qız portalı. Müntəzəm nümunələr, vahid səhv formatı və ciddi autentifikasiya sənədləri rəfdəki PDF-dən tərəfdaşları sürətləndirərək və dəstək xərclərini azaldaraq inteqrasiya üçün iş alətinə çevirəcəkdir.