Ҳуҷҷатҳои API: OpEN API, Swagger, Postman

TL; ДР

Open-API - манбаи ҳақиқат: шартнома → SDK → moki → tests → portal.
Swagger UI/Redoc - намоиши хондан; Почтачин - скриптҳои иҷрошаванда.
Мо дар линтерҳо, шикастани чекҳо, намунаҳо ва схемаҳои хатогӣ дӯхтем, серверҳои SDK ва Mock тавлид мекунем, портали девона ва "Ғуруби офтоб" -ро нашр мекунем.

1) Ҳадафҳо ва принсипҳо

Шартномаи якум (Open-API). Ҳама чизи дигар тавлид мешавад.
Ҳуҷҷатгузорӣ иҷрошаванда аст: дархостҳои намунавӣ дар Postman/CLI санҷида мешаванд.
Амнияти пешфарз: схемаҳои хатогӣ, маҳдудиятҳо, аутентификатсия.
Версия ва давраи зиндагӣ: 'v1 '/' v2', Амортизатсия/Ғуруби офтоб, changelog.

2) Сохтори кушодаи API (скелети ҳадди аққал)

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' }

• Ҷудо кардани схемаҳо/ҷавобҳо/параметрҳо/дархостҳо ба 'компонентҳо'.
• Нақшаҳои амниятро (OAuth2/JWT/HMAC) тавсиф кунед ва дар сатҳи 'роҳҳо '/' глобалӣ' татбиқ кунед.

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 (меъёри маҳдудият), 401/403 ва сарлавҳаҳои 'X-Rate' Limit- ',' Retry-After '-ро ҳуҷҷатгузорӣ кунед.

4) Намунаҳо: дархост/посух, curl ва SDK

Барои ҳар як нуқтаи ниҳоӣ: мисоли ҳадди аққал ва васеъ.
Эҷод кардани порчаҳои ҷингила ва рамз (JS/Python/Go) аз Open бо дасти худ нанависед.
Арзишҳои воқеиро татбиқ кунед: UUID, ISO-сана, маблағҳо дар "ноболиғ" (сент).

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 (интерактивӣ, санҷиш-берун),

2. Редок (саҳифаҳои дарозро хондан).

Дохил кунед: мавзӯи торик, ҷустуҷӯ, селектори версия ('v1', 'v2'), баннерҳои амортизатсия.

Барои домени истеҳсолӣ "Кӯшиш кунед" -ро пинҳон кунед, дар қуттии қуттӣ иҷозат диҳед.

6) Маҷмӯаҳои почтачиён: Скриптҳои зинда

Худоғоз кардани коллексия аз Open

Илова кардани пешпардохтҳо (гирифтани нишона) ва пост-тестҳо (тасдиқи вазъ/схемаҳо).
Ба ҷузвдонҳо ворид шавед: Auth, пардохтҳо, пардохтҳо, 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) Моки ва сандуқ

Тавлиди сервери масхара аз Open-API (мисолҳо/' мисол '/' мисолҳо ').
Маҳдудиятҳои mocsро нишон диҳед: номутобиқатӣ, таъхирҳо, хатогиҳои тасодуфӣ (барои UAT).
Қуттии ҳуҷҷат ва фарқияти prod (маҳдудиятҳо, маълумот, таъхирҳо).

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

Аз Open-API, SDK-ҳои расмиро тавлид кунед (TypE Script, Python, Go).
Сиёсати барориши SDK = Sem-Ver, харитасозии версияи API.
Дар README SDK: аутентификатсия, ретрай, аблаҳӣ, коркарди 429/Retry-After.

9) Линтинг, санҷиши шикастагӣ ва CI

Линтерҳо: спектралӣ (услубҳо/анти-намунаҳо), openapi-diff (шикастани чекҳо).

• валидатори ноҳиявӣ,
• линтер,
• озмоишҳои шартномавӣ бар зидди сервери ioc,
• Маҷмаи Swagger/Redoc/коллексия,
• нашр ба портал (марҳила → prod),
• Амортизатсия/Ҳушдори ғуруби офтоб.

10) Версия, фарсудашавӣ, ғуруби офтоб

Версия дар URI ('/v1 ') ва дар' маълумот. версия '.
Парчамҳои фарсудашавӣ: 'Фарсудашавӣ: ҳақиқӣ', 'Ғуруби офтоб: <RFC1123 сана>', 'Истинод: <changelog>' сарлавҳаҳо.
Дар портал - баннер ва вақтсанҷ пеш аз кандашавӣ; Маҷмӯаҳои почтачиён барои v1 ях бастаанд (танҳо ислоҳи хатогиҳо).

11) Амният ва махфият дар бандар

Сирри худро, URL-ҳои дохилӣ, PAN/PII-и воқеиро ҷойгир накунед.
Барои соҳаҳои ҳассос - намунаҳои ниқоб ва доғ.
Swagger "Кӯшиш кунед" → танҳо ба қуттии қуттӣ бо маҳдудиятҳои меъёрӣ.
Равшан аст, ки OAuth2/OIDC, HMAC (барои webhooks) ва MTLS (агар лозим бошад) тавсиф кунед.

12) Шартномаҳои роҳнамои услуб

Захираҳои зиёд: '/пардохтҳо ', '/пардохтҳо'.
Идентификаторҳо: 'пардохт _'', po _', UUIDv4 ё ksuid.
Санаҳо - UTC ISO-8601; пул - 'маблағ _ ноболиғ + асъор'.
Пагинатсия - курсор ('? курсор = & лимит = '), навъбандии устувор.
Idempotency - 'Idempotency-Key' барои мутатсия.
Объекти устувор 'meta' ва 'links' барои рӯйхатҳо.

13) Бахши "Вебхукҳо" -и док

Қисмати алоҳида бо лифофаи рӯйдодҳо, имзоҳои HMAC, равзанаи вақт, бозсозӣ, рамзҳои вокуниш.
Мақомоти чорабиниҳои намунавӣ ва ҷамъоварии Postman барои санҷиши имзоҳои маҳаллӣ.
нуқтаҳои такрорӣ/DLQ ва рӯйхати назоратии UAT.

14) Портали Dev: Нақшҳо ва нашр

Қисматҳо: Шарҳ, оғоз, аутентификатсия, нуқтаҳои ниҳоӣ, намунаҳо, вебхукҳо, SDK, маҳдудиятҳо, Changelog.
Нақшҳо: Steward API (стандартҳо), Соҳиби домейн (мундариҷа), Tech Writer (таҳрир), Деврел (портал/ҷомеа).
Хусусият: кофтуков тавассути майдонҳои схема, нусхабардории намунаҳо, "дархост ҷамъ кунед" → Почтачин.

15) Рӯйхати санҷишҳо

• API дуруст аст; linter бе хатогиҳо.
• Намунаҳо 200/4xx/429/5xx-ро дар бар мегиранд.
• Амният: нақшаҳои auth тавсиф карда мешаванд, ҳеҷ сирре нест.
• Swagger/Redoc ва Postman ташаккулёфта (prod/sandbox).
• SDK тавлид ва нашр шудааст.
• Навсозии changelog ва selector версия.

• Сарлавҳаҳои амортизатсия/ғуруби офтоб.
• Баннер дар портал, номаҳо ба шарикон.
• Нишондиҳандаҳои зангҳои меросӣ ба ҳадаф мерасанд.

16) Анти-намунаҳо

Манбаъҳои такрории ҳақиқат (wiki Open API).
Намунаҳои "бо чашм" бидуни давидан дар Постман.
Набудани формати ягонаи хатогӣ.
Версияи "дар параметрҳои дархост" ба ҷои URI/домен.
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) Маҳаллисозӣ ва мавҷудият

Индивидуалӣ. description_<lang>' ё ду маҷлисҳои порталӣ (EN/RU).
Истилоҳоти луғатӣ (KYC/AML, пардохт, idempotency).
Контраст, паймоиши клавиатура, мавзӯи торик.

Хулоса

Лӯлаи ҳуҷҷатҳоро ҷамъ кунед: як қарордоди ягонаи Open Мисолҳои мунтазам, формати ягонаи хатогӣ ва аутентификатсияи қавӣ ҳуҷҷатҳоро аз PDF дар раф ба воситаи ҳамгироии корӣ табдил медиҳанд, шариконро суръат мебахшанд ва хароҷоти дастгирӣ коҳиш медиҳанд.