مستندات API: OpenAPI، Swagger، پستچی

TL ؛ دکتر متخصص

OpenAPI - منبع حقیقت: قرارداد → SDK → moki → آزمایشها → پورتال.
UI Swagger/Redoc - ویترین قابل خواندن ؛ پستچی - اسکریپت های اجرایی.
ما در خطوط، شکستن چک، نمونه ها و طرح های خطا، تولید SDK ها و سرورهای ساختگی، انتشار یک پورتال توسعه نسخه و «غروب آفتاب».

1) اهداف و اصول

قرارداد اول (OpenAPI) هر چیز دیگری تولید می شود.
مستندات اجرایی است: درخواست های نمونه در Postman/CLI آزمایش می شوند.
امنیت پیش فرض: طرح های خطا، محدودیت ها، احراز هویت.
نسخه و چرخه زندگی: 'v1 '/' v2'، استهلاک/غروب خورشید، تغییرات.

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

• تجزیه طرحواره ها/پاسخ ها/پارامترها/requestBodies به 'components'.
• SecuritySchemes (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-RateLimit-'، 'Retry-After' را مستند کنید.

4) نمونه: درخواست/پاسخ، حلقه و SDK

برای هر نقطه پایانی: مثال حداقل و گسترده.
تولید قطعه های حلقه و کد (JS/Python/Go) از OpenAPI ؛ با دستهایتان ننویسید.
مقادیر واقعی را اعمال کنید: UUID، ISO-date، مبلغ در «جزئی» (سنت).

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. UI Swagger (تعاملی، امتحان کردن آن)،

2. Redoc (صفحات طولانی قابل خواندن).

شامل: تم تاریک، جستجو، انتخاب نسخه ('v1'، 'v2')، بنر استهلاک.

مخفی کردن «سعی کنید آن را» برای دامنه تولید، اجازه می دهد در sandbox.

6) مجموعه پستچی: اسکریپت زنده

جمع آوری خودکار از OpenAPI و پشتیبانی از متغیرهای محیطی ('{{baseUrl}}،' {{accessToken}}).
پیش آزمون (به دست آوردن یک نشانه) و پس آزمون (ادعا وضعیت/طرح) اضافه کنید.
شکستن به پوشه ها: 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) Moki و جعبه شن و ماسه

ایجاد یک سرور ساختگی از OpenAPI (examples/' example '/' examples ').
محدودیت های mocs را نشان می دهد: idempotency، تاخیر، خطاهای تصادفی (برای UAT).
سند sandbox در مقابل پیشنهاد تفاوت (محدودیت ها، داده ها، تاخیر).

8) تولید خودکار SDK

از OpenAPI، SDK های رسمی (TypeScript، Python، Go) تولید کنید.
سیاست انتشار SDK = SemVer، نقشه برداری نسخه API.
در README SDK: احراز هویت، بازپرداخت، idempotency، پردازش 429/Retry-After.

9) پوشش، بررسی شکستگی و CI

خطوط: طیفی (سبک/ضد الگوهای)، openapi-diff (شکستن چک).

• اعتبار سنج مدار، اعتبار سنج مدار,
• لینتر،
• تست قرارداد با IOC سرور
• Swagger/Redoc/مجموعه مونتاژ،
• انتشار به پورتال (مرحله بندی → prod)،
• هشدار کاهش/غروب آفتاب.

10) نسخه، تخفیف، غروب آفتاب

نسخه در URI ('/v1 ') و در' اطلاعات. نسخه '.
پرچمهای استهلاک: «استهلاک: درست»، «غروب آفتاب: <RFC1123 تاریخ>»، «پیوند: <changelog>» هدرها.
در پورتال - یک بنر و یک تایمر قبل از قطع ارتباط ؛ مجموعه پستچی برای v1 منجمد (رفع اشکال تنها).

11) امنیت و حریم خصوصی در اسکله

اسرار، URL های داخلی، PAN/PII واقعی را ارسال نکنید.
برای زمینه های حساس - masking and stub examples.
Swagger «آن را امتحان کنید» → فقط به sandbox، با محدودیت نرخ.
به وضوح OAuth2/OIDC، HMAC (برای webhooks) و mTLS (در صورت لزوم) را توصیف کنید.

12) قراردادهای راهنمای سبک

منابع جمع: «/پرداخت »، «/پرداخت».
شناسه ها: 'پرداخت _'،' po _'، UUIDv4 یا ksuid.
تاریخ - ISO-8601 UTC ؛ money - 'مقدار _ جزئی + ارز'.
صفحهبندی - مبتنی بر مکاننما) '؟ cursor = & limit = ')، مرتبسازی پایدار.
Idempotency - «Idempotency-Key» برای جهش ها.
شیء پایدار «meta» و «پیوندها» برای فهرستها.

13) بخش «Webhooks» اسکله

بخش جداگانه با پاکت رویداد، امضای HMAC، پنجره زمان، retrays، کدهای پاسخ.
نمونه بدن رویداد و مجموعه پستچی برای تایید امضای محلی.
پخش/نقطه پایانی DLQ و چک لیست UAT.

14) توسعه پورتال: نقش ها و انتشار

بخش ها: بررسی اجمالی، شروع کار، تأیید اعتبار، نقاط پایانی، نمونه ها، وب سایت ها، SDK، محدودیت ها، تغییرات.
نقش ها: API کارگزار (استانداردها)، مالک دامنه (محتوا)، نویسنده فنی (ویرایش)، DevRel (پورتال/جامعه).
ویژگی: جستجو از طریق زمینه های طرح، نمونه های کپی، «جمع آوری درخواست» → Postman.

15) چک لیست

• OpenAPI معتبر است ؛ لینک بدون خطا
• نمونه پوشش 200/4xx/429/5xx.
• امنیت: طرح auth شرح داده شده، هیچ راز.
• تشکیل Swagger/Redoc و پستچی (تولید/جعبه شن و ماسه).
• SDK تولید و منتشر شده است.
• به روز شده changelog و انتخابگر نسخه.

• هدر های تخفیف/غروب خورشید گنجانده شده است.
• بنر در پورتال، نامه به همکاران.
• معیارهای فراخوانی میراث به هدف سقوط می کنند.

16) ضد الگوهای

منابع تکراری حقیقت (ویکی ≠ OpenAPI).
نمونه هایی از «با چشم» بدون اجرا در Postman.

عدم وجود یک فرمت خطا

نسخه «در پارامتر پرس و جو» به جای 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).
کنتراست، ناوبری صفحه کلید، موضوع تاریک.

خلاصه

مونتاژ یک خط لوله از اسناد و مدارک: یک قرارداد OpenAPI → خطوط و چک کردن → ویترین Swagger/Redoc → مجموعه پستچی و یک سرور ساختگی → SDK → پورتال نسخه و غروب آفتاب. نمونه های منظم، یک فرمت خطای واحد و احراز هویت قوی، اسناد را از PDF در قفسه به یک ابزار ادغام کار، سرعت بخشیدن به شرکا و کاهش هزینه های پشتیبانی تبدیل می کند.