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 (interactive, try-it-out),

2. Redoc (окуу узун барактар).

Киргизиңиз: караңгы тема, издөө, версиялык селектор ('v1', 'v2'), Deprecation баннери.

Prod домен үчүн "Try it out" жашыруу, sandbox боюнча уруксат.

6) Postman Collection: жандуу жагдайлар

OpenAPI жыйнагын автогенерациялаңыз жана чөйрө өзгөрмөлөрүн колдоңуз ('{{baseUrl}}', '{{accessToken}}').
Претестдерди (токенди алуу) жана пост-тесттерди (статус/схемалар) кошуу.
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) Моки жана Сандбокс

OpenAPIден (мисалдар боюнча/' example '/' examples ') mock серверин түзүңүз.
mocha чектөөлөрдү белгилөө: демпотенттик, кечигүү, кокустук каталар (UAT үчүн).
Sandbox vs prod айырмачылыктарын документтештирүү (лимиттер, маалыматтар, кечигүүлөр).

8) SDK Autogeneration

OpenAPI расмий SDK түзүү (TypeScript, Python, Go).
SDK = SemVer чыгаруу саясаты, API чыгаруу боюнча mapping.
Жылы README SDK: Autentification, Retry, Idempotentity, 429/Retry-After иштетүү.

9) Линтинг, сынык текшерүү жана CI

Линтерс: spectral (стили/анти-үлгүлөрү), openapi-diff (breaking-текшерүү).

• схема валидатор,
• Линтер,
• contract tests vs мок-сервер,
• чогултуу Swagger/Redoc/чогултуу,
• порталга жарыялоо (staging → prod),
• Deprecation/Sunset жөнүндө эскертүү.

10) чыгаруу, Deprecation, Sunset

URI версиясы ('/v1 ') жана' info. version`.
Эскирген желектер: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
Порталда - баннер жана таймер өчүрүлгөнгө чейин; Postman-чогултуу үчүн v1 тоңдурулган (гана багфикстер).

11) Dock коопсуздук жана купуялык

Сырларды, ички URLлерди, реалдуу PAN/PIIлерди жарыялабаңыз.
Сезгич талаалар үчүн - камуфляж жана үлгү-муфталар.
Swagger "Try it out" → гана sandbox, rate-limits менен.
Так сүрөттөп OAuth2/OIDC, HMAC (Webhook үчүн) жана mTLS (зарыл болсо).

12) Style-Hyde келишимдер

көп санда ресурстар: '/payments ', '/payouts'.
ID 'pay _', 'po _', UUIDv4 же ksuid.
Даталар - UTC ISO-8601; акча - 'amount _ minor + currency'.
Pagination - cursor-based ('? cursor = & limit ='), туруктуу сорттоо.
Демпотенттүүлүк - мутациялар үчүн "Idempotency-Key".
Туруктуу объект 'meta' жана 'links' тизмелер үчүн.

13) Бөлүм "Webhooks" докто

Иш-чаранын конверти, HMAC кол тамгалары, убакыт терезеси, ретрайлер, жооп коддору менен өзүнчө бөлүм.
Жергиликтүү кол текшерүү үчүн окуялар жана Postman чогултуу дене мисалдар.
replay/DLQ жана UAT чек тизмеси.

14) Dev-портал: ролдору жана жарыялоо

Бөлүмдөр: Review, Start, Authentification, Endpoints, мисалдар, Webhuke, SDK, чектөөлөр, Changelog.
Ролдору: API Steward (стандарттар), Domain Owner (мазмун), Tech Writer (түзөтүү), DevRel (портал/коомчулук).
Ficha: схемалар талаалары боюнча издөө, үлгүлөрдү көчүрүп, "суроо-талап чогултуу" → Postman.

15) Чек баракчалары

• OpenAPI validen; Линтер катасыз.
• мисалдар 200/4xx/429/5xx камтыйт.
• Коопсуздук: сүрөттөлгөн схемалар auth, эч кандай сыр.
• Swagger/Redoc жана Postman (prod/sandbox) түзүлгөн.
• SDK тарабынан түзүлгөн жана жарыяланган.
• такташты changelog жана версия селектор.

• Deprecation/Sunset аталыштары камтылган.
• Баннер порталында, өнөктөштөргө кат.
• Эскирген чакырыктардын көрсөткүчтөрү максаттуу деңгээлге түшөт.

16) Анти-үлгүлөрү

Double чындык булактары (wiki ≠ OpenAPI).
Postman ишке жок "көзгө" мисалдар.
Каталардын бирдиктүү форматынын жоктугу.
URI/домендин ордуна "query-параметрде" версиясы.
Swagger азык-түлүк жана чек жок кирүү менен.
Макулдашылбаган пагинация жана аутентификация схемалары.

17) Mini автоматташтыруу 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) Локализация жана жеткиликтүүлүк

Жеке 'info. description_<lang>' же эки портал чогултуу (EN/RU).
Глоссарийдеги терминдер (KYC/AML, payout, idempotency).
Контраст, клавиатура багыттоо, караңгы тема.

Резюме

Документтердин конвейерин чогултуу: бирдиктүү OpenAPI-контракт → линтерлер жана breaking-checks → Swagger/Redoc витриналары → Postman коллекциялары жана мок-сервер → SDK → версиялоо жана Sunset менен чоң портал. Үзгүлтүксүз мисалдар, каталардын бирдиктүү форматы жана катуу аутентификация документтерди "текчедеги PDFден" интеграциянын жумушчу куралына айландырат, өнөктөштөрдү тездетет жана колдоонун баасын төмөндөтөт.