תיעוד API: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - מקור האמת: contract # SDK # moki + tess ac.portal.
סוואגר UI/Redoc - תצוגה קריאה; דוור - תסריטים ניתנים להפעלה.
אנחנו תופרים ספינים, שוברים-צ 'קים, דוגמאות ותוכניות שגיאות, יוצרים שרתי SDKs ו-Mock, מפרסמים פורטל dev ממולכד ו-Sunset.

1) מטרות ועקרונות

חוזה אחד (OpenAPI). כל השאר נוצר.
התיעוד ניתן להפעלה: בקשות מדגם נבחנות בדוור/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' }

טיפים

פירוק סכימות כמו/תגובות/פרמטרים/ גופים לתוך 'components'.
תאר הסכמות ( ) ותיישם ברמת ”נתיבים ”/” גלובליים”.

3) שגיאה סטנדרטית ו ־ metadata

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-EoutLimit-', '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. Swagger UI (אינטראקטיבי, לנסות את זה),

2. Redoc (דפים ארוכים ניתנים לקריאה).

כלל: ערכת נושא אפלה, חיפוש, בחירת גרסה (”v1”, ”v2”), כרזת Deprection.

הסתר ”נסה את זה” לתחום הייצור, לאפשר על ארגז החול.

6) אוספי דוור: תסריטים חיים

הגדרה אוטומטית של האוסף מ ־ OpenAPI ותמיכה במשתנים סביבתיים (”@ esheouurl”, ”@ escoToken”).
הוספת יומרות (השגת אסימון) ולאחר בדיקות (assert status/schemas).
לפרוץ לתיקיות: Auth, תשלומים, 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 (דוגמאות/” דוגמה ”/” דוגמאות ”).
הצג את המגבלות של המוקים: אידמפוטנטיות, עיכובים, שגיאות אקראיות (UAT).
תיבת חול של מסמך נגד הבדלי פרוד (גבולות, נתונים, עיכובים).

8) אוטוגנרציה SDK

מתוך OpenAPI, צור SDKs רשמי (TypeScript, Python, Go).
מדיניות שחרור SDK = SemVer, מיפוי גרסאות API.
ב-README SDK: אימות, מגש מחדש, אידמפוטנטיות, עיבוד 429/Retry-After.

9) לינטינג, בדיקת שבירה ומודיעה

לינטרס: ספקטרום (סגנונות/אנטי תבניות), openapi-diff (שבירת בדיקות).

• אימות מעגל,
• לינטר,
• בדיקות חוזה מול שרת היוק,
• הרכבה של Swagger/Redoc/Collection,
• פרסום לפורטל (היערכות = פרוד),
• התראת ירידה/שקיעה.

10) ורסינינג, דעיכה, שקיעה

גרסה ב ־ URI ('/v1 ') ובאינפורמציה. גרסה ".
דגלי פיטורים: 'Deprection: True', 'Sunset: <RFC1123 date>', 'Link: <changelog>' כותרות.
בפורטל - כרזה וטיימר לפני ניתוק; אוספי דוור עבור V1 קפואים (תיקוני באגים בלבד).

11) ביטחון ופרטיות ברציף

אין לפרסם סודות, כתובות פנימיות, פאן/פיל אמיתי.
לשדות רגישים - מיסוך ודוגמאות לספח.
סוואגר ”נסה את זה” = רק לארגז חול, עם מגבלות קצב.
תאר בבירור את OAuth2/OIDC, HMAC (עבור חוברות אינטרנט) ו-MTLS (במקרה הצורך).

12) חוזי מדריך סגנון

משאבים ברבים: '/תשלומים ', '/תשלום'.
מזהים: "שלם _', 'פו _', UUIDv4 או ksuid.
תאריכים - UTC ISO-8601; כסף - ”סכום _ מינור + מטבע”.
Pagination - מבוסס סמן ('? סמן = & גבול = "), מיון יציב.
אידמפוטנטיות - 'Idempotency-מפתח' עבור מוטציות.
אובייקט יציב 'meta' ו 'קישורים' לרשימות.

13) החלק "Webhooks' של המזח

חלק נפרד עם מעטפת אירוע, חתימות HMAC, חלון זמן, מגשים מחדש, קודי תגובה.
גופי אירוע לדוגמה ואוסף דוור לאימות חתימה מקומית.
הילוך חוזר/נקודות קצה DLQ ורשימת בדיקות UAT.

14) דב פורטל: תפקידים ופרסום

קטעים: סקירה, התחלה, אימות, נקודות קצה, דוגמאות, חוברות אינטרנט, SDK, הגבלות, Changelog.
תפקידים: Steward API (סטנדרטים), Domain בעלים (תוכן), Tech Writer (עריכה), DevRel (פורטל/קהילה).
תכונה: חיפוש בשדות סכימה, העתקה של דגימות, ”איסוף בקשה” * Postman.

15) רשימות בדיקה

[ ] OpenAPI תקף; לינטר ללא טעויות.

[ דוגמאות ] מכסות 200/4xx/429/5xx.

[ אבטחה ]: תכניות אוטומטיות מתוארות, ללא סודות.

[ ] נוצר Swagger/Redoc and Postman (תיבת חול).

[ ] SDK יצר ופרסם.

[ ] Changelog מעודכן ובורר גרסאות.

[ כלל ] כותרות Deprecation/Sunset.

[ ] באנר בפורטל, מכתבים לשותפים.

[ מדדי קריאת מורשת ] נופלים למטרה.

16) אנטי דפוסים

שכפול מקורות האמת (wiki everything OpenAPI).
דוגמאות של ”בעין” בלי לרוץ בדוור.
היעדר תבנית שגיאה אחת.
גרסה ”בפרמטר שאילתה” במקום 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, payout, idempotency).
ניגוד, ניווט מקלדת, נושא אפל.

תקציר

להרכיב צינור של תיעוד: חוזה OpenAPI אחד * linters ו-breaking-checks * Swagger/Redoc showcases ac Postman collections ו-SDK * portal ו-Sunset. דוגמאות רגילות, תבנית שגיאה אחת, ואימות חזק יהפכו את התיעוד מ-PDF על המדף לכלי אינטגרציה עובד,