توثيق API: OpenAPI و Swagger و Postman

TL; د

OpenAPI - مصدر الحقيقة: عقد → SDK → moki → اختبارات → البوابة.
Swagger UI/Redoc - عرض قابل للقراءة ؛ ساعي البريد - نصوص قابلة للتنفيذ.
نقوم بخياطة البطانات، وفحوصات الكسر، والأمثلة، ومخططات الخطأ، وإنشاء خوادم 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' }

نصائح

تحلل المخططات/الاستجابات/البارامترات/الطلب الأجسام إلى «عناصر».
وصف المخططات الأمنية (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, summs in «minor» (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 (تفاعلي، جربه)،

2. Redoc (صفحات طويلة قابلة للقراءة).

اشمل: السمة المظلمة، البحث، محدد الإصدار («v1»، «v2»)، لافتة الاستنكار.

إخفاء «جربها» لمجال الإنتاج، والسماح على صندوق الرمل.

6) مجموعات ساعي البريد: نصوص حية

قم بتوليد المجموعة من 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 (أمثلة/« مثال »/« أمثلة »).
يرجى الإشارة إلى القيود المفروضة على الموك: الخصوصية، والتأخير، والأخطاء العشوائية (بالنسبة إلى التوقيت العالمي الموحد).
المستند sandbox مقابل اختلافات prod (حدود، بيانات، تأخيرات).

8) التوليد الذاتي لـ SDK

من OpenAPI، قم بإنشاء SDKs الرسمية (TypeScript و Python و Go).
SDK release policy = SemVer, API version mapping.
في README SDK: المصادقة، إعادة الطباعة، الخصوصية، معالجة 429/Retry-After.

9) البطانة وفحص الكسر و CI

البطانات: الطيف (الأنماط/الأنماط المضادة)، openapi-diff (فحوصات الكسر).

• مصدق الدائرة،
• البطانة،
• اختبارات العقد ضد الخادم ioc،
• مجموعة Swagger/Redoc/Collection،
• النشر على البوابة (staging→prod)،
• الاستنكار/تنبيه غروب الشمس.

10) الإصدار، الاستنكار، غروب الشمس

النسخة في URI ('/v1 ') و' info. '.
أعلام الاستنكار: «Deprecation: true»، «Sunset: <RFC1123 date>»، «Link: <changelog>» headers.
في البوابة - لافتة ومؤقت قبل قطع الاتصال ؛ يتم تجميد مجموعات ساعي البريد لـ v1 (إصلاحات الأخطاء فقط).

11) الأمن والخصوصية في قفص الاتهام

لا تنشر الأسرار، عناوين URL الداخلية، PAN/PII الحقيقية.
للحقول الحساسة - أمثلة الإخفاء والكعب.
Swagger «جربها» → فقط لصندوق الرمل، مع حدود السعر.
وصف بوضوح OAuth2/OIDC، HMAC (لخطابات الويب) و mTLS (إذا لزم الأمر).

12) عقود دليل النمط

جمع الموارد: '/المدفوعات 'و '/المدفوعات'.
المعرفات: «دفع _'»، بو _'، UUIDv4 أو كسويد.
التواريخ - التوقيت العالمي المنسق ISO-8601 ؛ المال - «مبلغ _ صغير + عملة».
التثبيت - قائم على المؤشر (؟ المؤشر = & الحد = ')، فرز مستقر.
الخصوصية - «مفتاح الخصوصية» للطفرات.
كائن ثابت 'meta' و 'links' للقوائم.

13) قسم "Webhooks' في قفص الاتهام

قسم منفصل مع ظرف الحدث، توقيعات HMAC، نافذة الوقت، إعادة التصوير، رموز الاستجابة.
عينات من هيئات الأحداث وجمع ساعي البريد للتحقق من التوقيعات المحلية.
إعادة التشغيل/نقاط نهاية DLQ وقائمة مراجعة UAT.

14) بوابة Dev: الأدوار والنشر

الأقسام: نظرة عامة، البدء، المصادقة، نقاط النهاية، الأمثلة، شبكات الويب، SDK، القيود، التغيير.
الأدوار: Steward API (المعايير)، Domain Owner (المحتوى)، Tech Writer (التحرير)، DevRel (البوابة/المجتمع).
الميزة: البحث في حقول المخطط، عينات النسخ، «جمع الطلب» → ساعي البريد.

15) القوائم المرجعية

• واجهة برمجة التطبيقات المفتوحة صالحة ؛ دون أخطاء.
• تشمل الأمثلة 200/4xx/429/5xx.
• الأمن: المخططات الموصوفة، لا أسرار.
• تم تشكيل Swagger/Redoc و Postman (prod/sandbox).
• تم إنشاء SDK ونشرها.
• محدث التغيير ومحدد الإصدار.

• تم تضمين رؤوس الاستنكار/غروب الشمس.
• لافتة في البوابة، رسائل إلى الشركاء.
• تسقط مقاييس المكالمات القديمة في الهدف.

16) الأنماط المضادة

مصادر مكررة للحقيقة (ويكي ≠ OpenAPI).
أمثلة على «بالعين» دون الجري في ساعي البريد.
عدم وجود تنسيق خطأ واحد.
النسخة «in query parameter» بدلا من URI/domain.
التباهي مع الوصول إلى الطعام وبدون حدود.
مخططات الاستعداد والتوثيق غير المتسقة.

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، الدفع، الخصوصية).
التباين، التنقل في لوحة المفاتيح، السمة المظلمة.

موجز

قم بتجميع خط أنابيب من الوثائق: عقد OpenAPI واحد → بطانات وفحوصات كسر → يعرض Swagger/Redoc → مجموعات ساعي البريد وخادم وهمي → SDK → بوابة إصدار و Sunset. أمثلة منتظمة، وشكل خطأ واحد، ومصادقة قوية ستحول الوثائق من PDF على الرف إلى أداة تكامل عمل، وتسريع الشركاء وتقليل تكاليف الدعم.