API resminamalary: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - hakykat çeşmesi: şertnama → SDK → moki → synaglar → portal.
Swagger UI/Redoc - okalýan vitrin; Postman - ýerine ýetirilýän ssenariler.
Linterleri, breaking-checks, ýalňyşlyklaryň mysallaryny we shemalaryny tikýäris, SDK we Mock-serwerlerini öndürýäris, wersiýasy we "Sunset" bilen uly portaly çap edýäris.

1) Maksatlar we ýörelgeler

Bir şertnama (OpenAPI). Galan zatlaryň hemmesi döredilýär.
Resminamalar ýerine ýetirilip bilner: soraglaryň mysallary Postman/CLI-de synagdan geçirilýär.
Howpsuzlyk: ýalňyşlyklaryň, çäkleriň, tassyklamalaryň shemalary.
Wersiýa we durmuş aýlawy: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) OpenAPI gurluşy (iň az 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 -ni "components" -e ýerleşdiriň.
• securitySchemes (OAuth2/JWT/HMAC) belläň we 'paths '/' global' derejesinde ulanyň.

3) Ýalňyşlyklaryň we meta-maglumatlaryň standarty

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 }

Elmydama 429 (rate limit), 401/403 we "X-RateLimit-", "Retry-After" sözbaşylaryny resminamalaşdyryň.

4) Mysal üçin: request/response, curl we SDK

Her bir endpoint üçin: iň az we ösen mysal.
OpenAPI-den curl we kod snippetleri (JS/Python/Go) dörediň; eli bilen ýazmaň.
Hakyky bahalary goýuň: UUID, ISO-data, "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 - nädip çap etmeli

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

2. Redoc (okalýan uzyn sahypalar).

Açyň: gara tema, gözleg, wersiýa saýlaýjy ('v1', 'v2'), Deprecation banneri.

Prod-domen üçin "Try it out" -y gizläň, sandbox-da rugsat beriň.

6) Postman-kolleksiýalar: janly ssenariler

OpenAPI-den kolleksiýany awtogenerasiýa ediň we daşky gurşaw üýtgemelerini saklaň ('{{baseUrl}}', '{{accessToken}}').
Bellikleri we post-synaglary (assert status/shemalar) goşuň.
Aşakdaky bukjalara bölüň: Auth, Payments, Payouts, Webhooks.
Möhüm ugurlar üçin monitorlary (meýilnama boýunça) eksport ediň.

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 we sandboks

Mock-serweri OpenAPI-den dörediň (mysal üçin/' example '/' examples ').
Mok çäklendirmelerini belläň: idempotentlik, gijikdirmeler, tötänleýin ýalňyşlyklar (UAT üçin).
Sandbox vs prod tapawudyny resminamalaşdyryň (çäkler, maglumatlar, gijikdirmeler).

8) Awtogenerasiýa SDK

OpenAPI-den resmi SDK (TypeScript, Python, Go) dörediň.
SDK = SemVer çykaryş syýasaty, API wersiýasyna mapping.
README SDK-da: autentifikasiýa, retra, idempotentlik, 429/Retry-After gaýtadan işlemek.

9) Linting, döwülmegi barlamak we CI

Linterler: spectral (stiller/anti-patterns), openapi-diff (breaking-checks).

• shema tassyklaýjy,
• linter,
• mok serverine garşy contract tests,
• Swagger/Redoc/kolleksiýalary,
• portala ýerleşdirmek (staging → prod),
• Deprecation/Sunset duýduryşy.

10) Wersiýalaşdyrmak, Deprecation, Sunset

URI wersiýasy ('/v1 ') we' info. version`.
Könelişen baýdaklar: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
Portalda - banner we taýmer öçürilýänçä; Postman-kolleksiýalary v1 üçin doňduryldy (diňe bagfikler).

11) Gämi duralgasyndaky howpsuzlyk we gizlinlik

Syrlary, içerki URL-leri, hakyky PAN/PII-leri çap etmäň.
Duýgur ýerler üçin - kamuflaj we gysgyçly mysallar.
Swagger "Try it out" → diňe sandbox-a, rate-limits bilen.
OAuth2/OIDC, HMAC (webhook üçin) we mTLS (zerur bolsa).

12) Şertnamalaryň staýl-gaýdy

Köplükli çeşmeler: '/payments ', '/payouts'.
Kesgitleýjiler: 'pay _', 'po _', UUIDv4 ýa-da ksuid.
Seneler - UTC ISO-8601; pul - 'amount _ minor + currency'.
Paginasiýa - cursor-based ('? cursor = & limit ='), durnukly sortlama.
Idempotentlik - mutasiýa üçin 'Idempotency-Key'.
Sanawlar üçin 'meta' we 'links' durnukly obýekti.

13) Doktdaky "Webhooks" bölümi

Wakanyň konwerti, HMAC gollary, wagt penjiresi, retralary, jogap kodlary bilen aýratyn bölüm.
Wakalaryň jisimleriniň mysallary we goly ýerli barlamak üçin Postman ýygyndysy.
Replay/DLQ endpointleri we UAT çek sanawy.

14) Dev-portal: rollar we neşir etmek

Bölümler: syn, işe başlamak, Autentification, Endpoints, Mysallar, Webhuke, SDK, Çäklendirmeler, Changelog.
Rollar: API Steward (standartlar), Domain Owner (mazmun), Tech Writer (redaktirleme), DevRel (portal/jemgyýet).
Surat: shema meýdanlaryny gözlemek, sampllary göçürmek, "soragy ýygnamak" → Postman.

15) Çek-listler

• OpenAPI waliden; hatasyz linter.
• Mysallar 200/4xx/429/5xx.
• Howpsuzlyk: auth shemalary beýan edilýär, hiç hili syr ýok.
• Swagger/Redoc we Postman (prod/sandbox) tarapyndan döredildi.
• SDK tarapyndan döredildi we çap edildi.
• Changelog we wersiýa saýlaýjysy täzelendi.

• Deprecation/Sunset sözbaşylary goşuldy.
• Portalda banner, hyzmatdaşlara hat.
• Köne wersiýadaky jaňlaryň metrikleri maksat derejesine düşýär.

16) Anti-patternler

Hakykat çeşmeleri (wiki ≠ OpenAPI).
Postman-a başlamazdan "göz bilen" mysallar.
Ýeke-täk ýalňyşlyk formatynyň ýoklugy.
URI/domeniň ýerine "query-parametrde" wersiýasy.
Önüme girip bilýän we çäklendirmesiz Swagger.
Ylalaşylmadyk paginasiýa we autentifikasiýa shemalary.

17) Awtomatlaşdyrmagyň kiçi snippetleri

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) Lokalizasiýa we elýeterlilik

Aýry-aýry 'info. description_<lang>' ýa-da iki sany portal (EN/RU).
Sözlükdäki adalgalar (KYC/AML, payout, idempotency).
Kontrast, klawiatura nawigasiýasy, garaňky tema.

Gysgaça maglumat

Dokumentleriň konweýerini ýygnaň: ýeke-täk OpenAPI-şertnama → linterler we breaking-checks → Swagger/Redoc penjireleri → Postman kolleksiýalary we mok-serweri → SDK → wersiýasy we Sunset bilen uly portal. Yzygiderli mysallar, ýalňyşlyklaryň ýeke-täk görnüşi we berk tassyklama resminamalary "tekjedäki PDF" -den integrasiýa iş guralyna öwürer, hyzmatdaşlary çaltlaşdyrar we goldawyň bahasyny azaldar.