API დოკუმენტაცია: OpenAPI, Swagger, Postman

TL; DR

OpenAPI არის ჭეშმარიტების წყარო: ხელშეკრულება SDK - ხიდები, ტესტები და პორტალი.
Swagger UI/Redoc - წაკითხული ფანჯარა; Postman - შესრულებული სკრიპტები.
ჩვენ ვსვამთ საბრძოლო მასალებს, ყუთების შემოწმებებს, მაგალითებსა და შეცდომების ნიმუშებს, წარმოქმნის 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'.
• აღწერეთ 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 (საბაზო ლიმიტი), 401/403 და სათაურები „X-RateLimit-“, 'Retry-After'.

4) მაგალითები: request/response, curl და SDK

თითოეული ენდოინტისთვის: მინიმალური და გაფართოებული მაგალითი.
წარმოქმნის curl და კოდი snippets (JS/Python/Go) OpenAPI- დან; ნუ დაწერთ ხელებს.
გამოიყენეთ რეალური მნიშვნელობები: 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 (ინტერაქტიული, try-it-out),

2. Redoc (გრძელი კითხვის გვერდები).

ჩართეთ: ბნელი თემა, ძებნა, ვერსიის სელექტორი ('v1', 'v2'), დეპრესიის ბანერი.

დამალეთ „გზა გარეთ“ პროდ დომენისთვის, დაუშვით sandbox.

6) Postman კოლექციები: ცოცხალი სცენარები

OpenAPI- სგან მიღებული კოლექცია და შეინარჩუნეთ გარემოსდაცვითი ცვლადები ('{baseUrult}', '{{Token}}').
დაამატეთ პრეტესტები (ნიშნის მოპოვება) და პოსტ ტესტები (სტატუსის/სქემების ასორტი).
გაეცანით მამებს: 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 ').
მიუთითეთ მოცვის შეზღუდვები: idempotence, შეფერხება, შემთხვევითი შეცდომები (UAT- სთვის).
აღწერეთ განსხვავებები sandbox vs (ლიმიტები, მონაცემები, შეფერხებები).

8) SDK ავტომატური წარმოება

OpenAPI- დან ჩამოაყალიბეთ ოფიციალური SDK (TypeScript, Python, Go).
SDK = SemVer გამოშვების პოლიტიკა, API ვერსიის მაპინგი.
README SDK: ავთენტიფიკაცია, retrais, imempotence, დამუშავება 429/Retry-After.

9) ლინტინგი, დარღვევების შემოწმება და CI

Linters: spectral (სტილი/ანტი-ნიმუშები), openapi-diff (breaking-checks).

• მიკროსქემის დამადასტურებელი
• ლინტერი
• contract tests წინააღმდეგ mock სერვერი,
• Swagger/Redoc/კოლექციების ასამბლეა,
• პუბლიკაცია პორტალზე (staging),
• შეტყობინება Deprecation/Sunset.

10) ვერსია, Deprecation, Sunset

ვერსია URI ('/v1 ') და' info. version`.
მოძველებული დროშები: სათაურები 'დეპრესია: ნამდვილი', 'Sunset: <RFC123 date>', 'Link: <changelog>'.
პორტალში - ბანერი და ტაიმერი გათიშვამდე; Postman კოლექციები v1- სთვის გაყინულია (მხოლოდ ბარგები).

11) უსაფრთხოება და კონფიდენციალურობა დოქში

არ გამოაქვეყნოთ საიდუმლოებები, შიდა URL, რეალური PAN/PII.
მგრძნობიარე ველებისთვის - შენიღბვა და მაგალითები-დანამატები.
Swagger „Try it out“ მხოლოდ sandbox- სთვის არის, რბოლა-ლიმიტები.
მკაფიოდ აღწერეთ OAuth2/OIDC, HMAC (ვებჰუკებისთვის) და mTLS (საჭიროების შემთხვევაში).

12) ხელშეკრულებების ძირითადი

რესურსები მრავლობითში: '/payments ', '/payouts'.
იდენტიფიკატორები: 'გადახდა _', 'po _', UUIDv4 ან ksuid.
თარიღები - UTC ISO-8601; ფული - 'amount _ minor + currency'.
Pagination - cursor-based ('? cursor = & limit ='), სტაბილური დახარისხება.
Idempotence - 'Idempotency-Key' მუტაციებისთვის.
სტაბილური ობიექტი 'meta' და 'links' სიებისთვის.

13) Webhooks განყოფილება დოქში

ცალკეული განყოფილება ღონისძიების კონვერტით, HMAC ხელმოწერებით, დროის ფანჯრით, რელიეფით, პასუხის კოდებით.
მოვლენების ორგანოების მაგალითები და Postman- ის კოლექცია ხელმოწერის ადგილობრივი შემოწმებისთვის.
Endpoints replay/DLQ და UAT ჩეკების სია.

14) საზაფხულო პორტალი: როლები და პუბლიკაცია

სექციები: მიმოხილვა, მუშაობის დასაწყისი, ავთენტიფიკაცია, ენდოინტები, მაგალითები, ვებჰუკი, SDK, შეზღუდვები, ჩანგელოგი.
როლები: API Steward (სტანდარტები), Domain Owner (შინაარსი), Tech Writer (რედაქტორი), DevRel (პორტალი/საზოგადოება).
Fich: სქემების ძიება, samples- ის კოპირება, Postman- ის „თხოვნის შეგროვება“.

15) ჩეკის ფურცლები

• OpenAPI სავალდებულოა; ლინტერი შეცდომის გარეშე.
• მაგალითები დაფარულია 200/4xx/429/5xx.
• უსაფრთხოება: აღწერილია auth სქემები, არ არსებობს საიდუმლოებები.
• ჩამოყალიბდა Swagger/Redoc და Postman (sandbox).
• SDK წარმოიქმნება და ქვეყნდება.
• განახლებულია changelog და ვერსიის სელექტორი.

• Deprecation/Sunset სათაურები შედის.

ბანერი პორტალშია, პარტნიორების წერილები.

• მოძველებული ვერსიის გამოწვევების მეტრიკა სამიზნე დონეზე ეცემა.

16) ანტი შაბლონები

ჭეშმარიტების სარეზერვო წყაროები (ვიკი - OpenAPI).
მაგალითები „თვალზე“ Postman- ში გაშვების გარეშე.
შეცდომების ერთიანი ფორმატის არარსებობა.
ვერსია „query პარამეტრში“ URI/დომენის ნაცვლად.
Swagger prod და limites გარეშე.
არაკოორდინირებული პაგინაცია და ავტორიზაციის სქემები.

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, idempotence).
კონტრასტი, კლავიატურის ნავიგაცია, ბნელი თემა.

რეზიუმე

შეაგროვეთ დოკუმენტაციის კონვეიერი: ერთი OpenAPI კონტრაქტი - Linters და breaking checks - Swagger/Redoc, Postman კოლექციის ფანჯრები და mock სერვერი - SDK - dev პორტალი ვერსიით და Sunset. რეგულარული მაგალითები, შეცდომების ერთიანი ფორმატი და მკაცრი ავთენტიფიკაცია PDF- დან დოკუმენტაციას თაროზე გადააქცევს ინტეგრაციის სამუშაო ინსტრუმენტად, აჩქარებს პარტნიორებს და ამცირებს მხარდაჭერის ღირებულებას.