API 'OpenAPI, Swagger, Postman

TL; DR

OpenAPI-ը ճշմարտության աղբյուրն է 'MSK-ի պայմանագիրը մոսկովյան կամուրջները։

Swagger UI/Redoc - ընթերցվող վիտրինը; Postman-ը կատարված սցենարներ են։

Մենք հավաքում ենք ոսպնյակներ, breaking-winks, օրինակներ և սխալների սխեմաներ, որոնք համապատասխանում են MSK և Mock սերվերներին, հրապարակում ենք dev պորտալը տարբերակով և 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' }

Խորհուրդ

Տեղադրեք շեմաս/responses/parameters/requestBodies-ում։

Նկարագրեք Schemes (OAuth2/JWT/HMAC) և օգտագործեք «paths »/« global» մակարդակում։

3) Սխալների և մետատվողների իրականացումը

Մեկ սխալ օբյեկտ (ինչպես REST, այնպես էլ webhuks)

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-Rance Limit-», «Retry-After» վերնագրերը։

4) Օրինակներ ՝ request/response, curl և MSK

Յուրաքանչյուր էնդպոինտի համար նվազագույն և ընդլայնված օրինակ է։

Ստեղծեք curl և compets (JS/Python/Go) OpenAPI-ից։ մի գրեք ձեռքերով։

Կիրառեք իրական արժեքներ 'UUID, IV-ամսաթիվը, գումարները «փոքրամասնություններում» (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-ը։

Թույլ տվեք sandbox-ում։

6) Postman հավաքածուներ 'կենդանի սցենարներ։

Autogenerium հավաքածու OpenAPI-ից և աջակցեք շրջակա միջավայրի պարամետրերին ("www.Rurce +," "wwww.Token + + +)։

Ավելացրեք գայթակղությունները (հոսանքի ստացումը) և փոստի թեստերը (assoft կարգավիճակը/սխեմաները)։

Թալանել հայրերին '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-ի mock սերվերը (պատճեններով/« example »/« examples »)։

Նշեք կամուրջների սահմանափակումները 'կուռքեր, ձգձգումներ, պատահական սխալներ (UAT)։

Փաստաթղթավորեք sandbox vs-ի տարբերությունները (լիմիտներ, տվյալներ, ուշացումներ)։

8) MSK ավտոտրանսպորտը

OpenAPI-ից ստեղծեք պաշտոնական SDK (No Script, Python, Go)։

SDK = SemVer ֆորումների քաղաքականությունը, API տարբերակը։

READOM READA-ում 'վավերացում, ռեակտորներ, գաղափարախոսություն, 429/Retry-After վերամշակում։

9) Լինթինգը, կոտրվածքների ստուգումը և CI-ը

Linters: spectral (պողպատե/anti-pattern), openapi-diff (breaking-winks)։

• սխեմայի վաիդատոր,
• linter
• www.ract tes.ru դեմ
• Swagger/Redoc/հավաքածուի հավաքածու,
• պորտալի հրապարակումը (staging no),
• ծանուցում Deprecation/Sunset-ի մասին։

10) Տարբերակումը, Deprecation, Sunset

URI-ի տարբերակը ('/v1 ") և '։ version`.

Հնազանդության դրոշները '«Deprecation: 108», «Sunset: ,» Link: ։

Պորտալում 'դրոշը և թայմերը մինչև 2019 թվականը։ Postman հավաքածուները v1-ի համար սառեցված են (միայն ուղեբեռները)։

11) Ապահովությունն ու մասնավորությունը դաջվածքում

Մի հրապարակեք գաղտնիքները, ներքին URL-ը, իրական PAN/PII-ը։

Զգայուն դաշտերի համար 'դիմակավորում և հալեցման օրինակներ։

Swagger «Try it out» -ը նշվում է միայն sandbox-ի, rate-limits-ի հետ։

Հստակ նկարագրել OAuth2/OIDC, HMAC (webhuks) և mTSA (եթե պահանջվում է)։

12) Stail-interd

Ռեսուրսները շատ թվով ՝ «/payments », «/payouts»։

Բաղադրիչները ՝ «բանաձև _», «po _», UUIDv4 կամ ksuid։

Ամսաթվերը UTC IV-8601; փողը 'amount _ minor + currency "։

Պագինացիա - cursor-based («? cursor = & limit =»), կայուն տեսակավորում։

Idempotenty-Key-ը մուտացիաների համար։

Կայուն օբյեկտ «meta» և «links» ցուցակների համար։

13) «Webhooks» բաժինը նավահանգստում

Առանձնահատուկ բաժին իրադարձության փոխարկմամբ, HMAC ստորագրություններով, ժամանակի պատուհաններով, ելույթներով, պատասխանների կոդերով։

Իրադարձությունների մարմինների օրինակները և Postman հավաքածուն տեղական ստորագրության ստուգման համար։

Endpoints replay/DLQ-ը և UAT-ի չեկը։

14) Դև պորտալը 'դերեր և հրատարակություններ

Բաժինները ՝ Ակնարկ, Աշխատանքի սկիզբ, Վավերացում, Էնդպոինտա, Օրինակներ, Վեբհուկի, MSK, Սահմանափակումներ, Changelog։

Դերերը ՝ API Steward (ստանդարտներ), Domain Owner (բովանդակություն), Tech Writer (խմբագրություն), DevRel (պորտալ/համայնք)։

Ֆիչա 'որոնել սխեմաները, պատճենել սեմպլները, «հավաքել հարցումը» www.Postman-ի համար։

15) Չեկ թերթերը

Նախքան ֆորումը

• OpenAPI validen; linter առանց սխալների։
• Օրինակները ծածկում են 200/4xx/429/5xx։
• Անվտանգություն. Նկարագրված է auth սխեմաները, գաղտնիքներ չկան։
• Ձևավորվում են Swagger/Redoc և Postman (07/sandbox)։
• Sgenerations CPK-ը և հրապարակվում են։
• Չանգելոգը և տարբերակիչ բուծողը նորարարված են։

Deprecation-ի համար

• Deprecation/Sunset վերնագրերը ներառված են։
• Բանները պորտալում, նամակներ։
• Հնացած տարբերակի մարտահրավերները ընկնում են նպատակային մակարդակին։

16) Anti-patterna

Կրկնվող ճշմարտության աղբյուրները (viki API)։

«Աչքերի վրա» օրինակները առանց Postman-ի գործարկման։

Սխալների միասնական ձևաչափի բացակայությունը։

«Query-pro» տարբերակը URI/տիրույթի փոխարեն։

Swagger հասանելիություն և առանց սահմանների։

Չհամաձայնեցված սագինացիա և սխեմաներ։

17) Ավտոմատացման մինի-չիպետներ

OpenAPI-ից Postman հավաքածուի գեներալը (կեղծ)

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

Պորտալի հրապարակումը (CI քայլերը, կեղծ-YAML)

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) Տեղայնացումը և հասանելիությունը

Առանձին '108։ descultion _ կամ պորտալի երկու հավաքածուներ (EN/RU)։

Տերմինները գլոսարիայում (KYC/AML, payout, idempotency)։

Հակադրություն, ստեղնաշարային ռոտացիա, մութ թեմա։

Ռեզյումե

Հավաքեք փաստաթղթերի փոխակրիչը 'մեկ OpenAPI-պայմանագիր ռուսական ոսպնյակներ և breaking-winks Wwagger/Redoc words wwww.Postman-ը և Snset-ը։ Նշված օրինակները, սխալների միասնական ձևաչափը և խիստ վավերացումը կդարձնեն «PDF» -ի փաստաթղթերը ինտեգրման աշխատանքային գործիք, արագացնելով գործընկերները և նվազեցնելով աջակցության արժեքը։