הגדרת Swagger UI / ReDoc לתיעוד API אינטראקטיבי

הגדרת Swagger UI / ReDoc לתיעוד API אינטראקטיבי

כשה-API גדל למאות נקודות קצה, תיעוד ידני הופך לעקב האכילס של הפרויקט

שותפים מתלוננים על תגובות לא ברורות, מפתחים מבזבזים שעות בחיפוש אחר המתודה הנכונה — אנחנו נתקלים בזה בכל פרויקט שני. הגדרת Swagger UI, ReDoc או Scalar פותרת את הבעיה תוך 0.5–2 ימים. תיעוד אינטראקטיבי עם כפתור Try it out, אימות זהות ועיצוב מותאם אישית הוא הסטנדרט של פיתוח מודרני. במשך יותר מ-5 שנים, חיסלנו את הבעיות האלה ביותר מ-30 פרויקטים — מסטארטאפים ועד מערכות ארגוניות — תוך צמצום זמן האינטגרציה פי 2–3 וחיסכון של כ-$9–13 בשנה ללקוחות בתמיכה.

בעיות שאנחנו פותרים

תיעוד ידני מתיישן אחרי שבועיים — זו עובדה. לפי מפרט OpenAPI, הוא חי יחד עם הקוד, וכלים כמו Swagger UI ו-ReDoc הופכים אותו למדריך אינטראקטיבי ללא עריכה ידנית אחת. טעויות אופייניות: CORS לא מוגדר (בקשות מ-Swagger UI הולכות לריק), persistAuthorization חסר (טוקן מתאפס בכל טעינה מחדש), או תיעוד שלא מתעדכן ב-CI pipeline. אנחנו מבטלים את הבעיות האלה כבר בשלב החיבור. התוצאה היא צמצום זמן האינטגרציה פי 2–3. בפרויקט אחד לסטארטאפ פינטק, פרסנו Scalar עם דומיין מותאם אישית ואימות זהות — הצוות הפסיק לבזבז 10 שעות בשבוע בהסברים למשל�בים, ועומס התמיכה ירד ב-60%.

תהליך הגדרת תיעוד API ב-4 שלבים

אנחנו עוקבים אחר תהליך ברור כדי להבטיח שהתיעוד עדכני וידידותי למשתמש:

1. ניתוח API: חקר המפרט, נקודות הקצה, סכמות הנתונים.
2. בחירת כלי: Swagger UI לפיתוח, ReDoc או Scalar לתיעוד ציבורי.
3. חיבור והתאמה אישית: הגדרת סגנונות, אימות זהות, CI/CD.
4. פריסה ותמיכה: אירוח, עדכון אוטומטי בכל פריסה.

איך להוסיף Swagger UI ל-API שלך

עבור Express.js, אנחנו משתמשים בחבילת swagger-jsdoc ו-swagger-ui-express. אנחנו מייצרים את המפרט מהערות JSDoc, רושמים את הנתיב /docs — התיעוד מוכן תוך 15 דקות:

import swaggerUi from 'swagger-ui-express';
import swaggerJsdoc from 'swagger-jsdoc';

const spec = swaggerJsdoc({
  definition: {
    openapi: '3.1.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/**/*.js'],
});

app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec, {
  customCss: '.swagger-ui .topbar { display: none }',
  swaggerOptions: {
    persistAuthorization: true,
  },
}));

ב-FastAPI, תיעוד ב-import swaggerUi from 'swagger-ui-express'; import swaggerJsdoc from 'swagger-jsdoc'; const spec = swaggerJsdoc({ definition: { openapi: '3.1.0', info: { title: 'My API', version: '1.0.0' }, }, apis: ['./routes/**/*.js'], }); app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec, { customCss: '.swagger-ui .topbar { display: none }', swaggerOptions: { persistAuthorization: true }, })); ו-/docs מופיע אוטומטית. אם צריך Scalar, שלוש שורות קוד:

from scalar_fastapi import get_scalar_api_reference

@app.get("/scalar", include_in_schema=False)
async def scalar_html():
    return get_scalar_api_reference(openapi_url="/openapi.json", title="API Reference")

עבור Laravel, אנחנו ממליצים על חבילת Scramble — היא רושמת את הנתיב /redoc עם ממשק Stoplight Elements.

מה לבחור: Swagger UI, ReDoc או Scalar?

Swagger UI אידיאלי לפיתוח וניפוי באגים: כפתור Try it out מאפשר לשלוח בקשות ישירות מהדפדפן. ReDoc טוב יותר לקריאה במובייל ומתאים לתיעוד ציבורי. Scalar הוא אלטרנטיבה מודרנית שמשלבת את האינטראקטיביות של Swagger UI עם הקריאות של ReDoc. כל השלושה תומכים ב-OpenAPI 3.1, אבל Scalar נטען מהר יותר ומציע התאמה אישית גמישה יותר. לדוגמה, בפרויקט אחד עברנו מ-Swagger UI ל-Scalar והקטנו את זמן טעינת דף התיעוד ב-40%.

ציר זמן לפי שלבים

מה כלול בפתרון מפתח

אנחנו צוות עם יותר מ-5 שנות ניסיון והשלמנו יותר מ-30 פרויקטים של הגדרת תיעוד API. אנחנו לוקחים אחריות מלאה:

• יצירת מפרט OpenAPI ל-API שלך;
• חיבור והגדרה של Swagger UI / ReDoc / Scalar;
• התאמת סגנונות למותג שלך (לוגו, צבעים);
• הגדרת אימות זהות (Bearer token, OAuth2) עם persistAuthorization;
• אינטגרציית CI/CD (עדכון אוטומטי בפריסה);
• אירוח תיעוד (אתר סטטי על כל פלטפורמה).

אנחנו מבטיחים שהתיעוד יהיה עדכני בעת המסירה.

התאמה אישית ואימות זהות

עבור APIs עם Bearer token, אנחנו מגדירים from scalar_fastapi import get_scalar_api_reference @app.get("/scalar", include_in_schema=False) async def scalar_html(): return get_scalar_api_reference(openapi_url="/openapi.json", title="API Reference") ב-Swagger UI — הטוקן נשמר בין טעינות מחדש. ב-ReDoc, אנחנו מוסיפים /docs/api ו-persistAuthorization לקיבוץ נקודות קצה. דוגמה למפרט OpenAPI:

---
info:
  x-logo:
    url: 'https://example.com/logo.png'
  x-tagGroups:
    - name: Core
      tags: [users, projects]
    - name: Billing
      tags: [subscriptions, invoices]
---

איך לשמור על תיעוד מעודכן בפריסה?

הוסיפו שלב ב-pipeline שמייצר את מפרט ה-OpenAPI ופורס תיעוד סטטי. אנחנו משתמשים ב-GitHub Actions או GitLab CI לאוטומציה — זה מבטיח שהתיעוד תמיד מסונכרן עם הקוד. אנחנו מספקים דוגמת הגדרה.

אירוח תיעוד

שלוש אפשרויות: להטמיע באפליקציה (נתיב x-logo), לפרוס כאתר סטטי נפרד, או להשתמש בשירות מתארח (SwaggerHub, Readme.io). האפשרות הסטטית היא האמינה ביותר: אנחנו מייצאים את מפרט ה-OpenAPI ב-CI, פורסים Scalar/ReDoc ל-GitHub Pages או Cloudflare Pages. התיעוד תמיד זמין ואינו תלוי בזמינות שרת ה-API.

ציר זמן

הגדרת Swagger UI או ReDoc בסיסית לאפליקציה קיימת — 0.5–1 יום. סגנון מותאם אישית ואימות זהות — יום אחד. מעבר ל-Scalar עם דומיין מותאם אישית — 1–2 ימים. הזמינו הגדרת תיעוד API במפתח — קבלו ייעוץ. צרו קשר כדי לדון בפרטי הפרויקט שלכם ולהעריך את החיסכון בתקציב.