API құжаттамасы: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - ақиқат көзі: келісімшарт → SDK → моки → тесттер → портал.
Swagger UI/Redoc - оқылатын витрина; Postman - орындалатын сценарийлер.
Линтерлер, breaking-checks, мысалдар мен қателер схемаларын тігеміз, SDK және Mock-серверлерді генералаймыз, нұсқасы бар және «Sunset» торабын жариялаймыз.

1) Мақсаттар мен қағидаттар

Бір келісімшарт (OpenAPI). Қалғандарының бәрі жинақталады.
Құжаттама орындалады: сұрау үлгілері Postman/CLI-де тестіленеді.
Әдепкі қауіпсіздік: қателер, лимиттер, аутентификация схемалары.
Нұсқалау және өмірлік цикл: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) OpenAPI құрылымы (ең кіші скелет)

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' ішіне орналастырыңыз.
• securitySchemes (OAuth2/JWT/HMAC) сипаттау және 'paths '/' global' деңгейінде қолдану.

3) Қателер мен метадеректер стандарты

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 }

429 (rate limit), 401/403 және 'X-RateLimit-', 'Retry-After' тақырыптарын әрқашан құжаттаңыз.

4) Мысалдар: request/response, curl және SDK

Әрбір эндпоинт үшін: ең аз және кеңейтілген мысал.
OpenAPI бағдарламасынан curl және код сниппеттерін (JS/Python/Go) жасаңыз; қолмен жазба.
Нақты мәндерді қолданыңыз: UUID, ISO-күні, «шағын» (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 - қалай жариялау керек

1. Swagger UI (интерактив, try-it-out),

2. Redoc (оқылатын ұзын беттер).

Қараңғы тақырыпты, іздеуді, нұсқалық селекторды ('v1', 'v2'), Deprecation баннерін қосыңыз.

Прод-домен үшін «Try it out» дегенді жасырыңыз, sandboxқа рұқсат етіңіз.

6) Postman-коллекциялар: тірі сценарийлер

OpenAPI жиынын автоматты түрде жасаңыз және қоршаған ортаның айнымалыларына қолдау көрсетіңіз ('{{baseUrl}}', '{{accessToken}}').
Претесттерді (токенді алу) және пост-тестерді (assert мәртебесін/схемаларын) қосыңыз.
Auth, Payments, Payouts, Webhooks қалталарына бөліңіз.
Күрделі бағыттар үшін мониторларды (кесте бойынша) экспорттаңыз.

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) Моки және сэндбокс

Mock-серверін OpenAPI бағдарламасынан жасаңыз (мысалы/' example '/' examples ').
Шыбын шектеулерін белгілеңіз: иілгіштік, кідірістер, кездейсоқ қателер (UAT үшін).
Sandbox vs prod айырмашылықтарын құжаттаңыз (лимиттер, деректер, кідірістер).

8) SDK автогенерациясы

OpenAPI бағдарламасынан ресми SDK (TypeScript, Python, Go) жасаңыз.
SDK = SemVer релиздер саясаты, API нұсқасына маппинг.
README SDK-да: аутентификация, ретра, идемпотенттілік, 429/Retry-After өңдеу.

9) Линтинг, сынуды тексеру және CI

Линтерлер: spectral (стильдер/қарсы үлгілер), openapi-diff (breaking-checks).

• схема валидаторы,
• линтер,
• contract tests мок-серверге қарсы,
• Swagger/Redoc/коллекцияларын жинау,
• порталға жариялау (staging → prod),
• Deprecation/Sunset туралы хабарландыру.

10) Нұсқалау, Deprecation, Sunset

URI ('/v1 ') және' info. version`.
Ескіру жалаушалары: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
Порталда - баннер мен таймер өшірілгенге дейін; v1 үшін Postman-коллекциялары мұздатылған (тек багфикстер).

11) Доктағы қауіпсіздік және құпиялылық

Құпияларды, ішкі URL, нақты PAN/PII жарияламаңыз.
Сезімтал өрістер үшін - бүркемелеу және бітеу-мысалдар.
Swagger «Try it out» → тек sandbox, rate-limits.
OAuth2/OIDC, HMAC (вебхуктер үшін) және mTLS (егер қажет болса) нақты сипаттаңыз.

12) Келісімшарттардың стайл-гайды

Көпше түріндегі ресурстар: '/payments ', '/payouts'.
Идентификаторлар: 'pay _', 'po _', UUIDv4 немесе ksuid.
Күні - UTC ISO-8601; ақша - 'amount _ minor + currency'.
Пагинация - cursor-based ('? cursor = & limit ='), тұрақты сұрыптау.
Мутацияға арналған «Idempotency-Key».
Тізімдер үшін 'meta' және 'links' тұрақты нысаны.

13) Доктағы «Webhooks» бөлімі

Оқиға конверті, HMAC қолдары, уақыт терезесі, ретрайлері, жауап кодтары бар жеке бөлім.
Оқиға денесінің мысалдары және қолтаңбаны жергілікті тексеру үшін Postman жиыны.
replay/DLQ эндпоинттері және UAT чек парағы.

14) Dev-портал: рөлдер және жариялау

Бөлімдер: Шолу, Жұмысты бастау, Аутентификация, Эндпоинттер, Мысалдар, Вебхактар, SDK, Шектеулер, Changelog.
Рөлдері: API Steward (стандарттар), Domain Owner (контент), Tech Writer (редакция), DevRel (портал/қоғамдастық).
Фича: схема өрістерін іздеу, сэмплдарды көшіру, «сұрауды жинау» → Postman.

15) Чек парақтары

• OpenAPI валиден; қатесіз линтер.
• Мысалдар 200/4xx/429/5xx қамтиды.
• Қауіпсіздік: auth схемалары сипатталған, құпия жоқ.
• Swagger/Redoc және Postman (prod/sandbox) құрылды.
• SDK құрылды және жарияланды.
• changelog және нұсқалық селектор жаңартылды.

• Deprecation/Sunset тақырыптары қосылған.
• Порталдағы баннер, серіктестерге хаттар.
• Ескірген нұсқаның шақырулар өлшемдері мақсатты деңгейге түседі.

16) Қарсы үлгілер

Қайталанатын ақиқат көздері (вики ≠ OpenAPI).
Postman бағдарламасында іске қосылмайтын «көзбе-көз» мысалдары.
Бірыңғай қате пішімінің болмауы.
URI/доменнің орнына «query-параметрде» нұсқасы.
Swagger өнімге қолжетімділікпен және лимитсіз.
Келісілмеген пагинация және аутентификация схемалары.

17) Автоматтандырудың шағын сниппеттері

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) Оқшаулау және қол жетімділік

Жеке 'info. description_<lang>' немесе екі портал жинағы (EN/RU).
Глоссарийдегі терминдер (KYC/AML, payout, idempotency).
Қарама-қарсылық, пернетақталық навигация, қараңғы тақырып.

Түйіндеме

Құжаттама конвейерін жинаңыз: бірыңғай OpenAPI-келісімшарт → линтерлер және breaking-checks → Swagger/Redoc витриналар → Postman коллекциялары және мок-сервер → SDK → dev-портал нұсқасы және Sunset. Тұрақты мысалдар, қателердің бірыңғай форматы және қатаң сәйкестендіру құжаттарды «сөреде PDF» -тен интеграцияның жұмыс құралына айналдырады, әріптестерді жеделдетеді және қолдау құнын төмендетеді.