پرش به مطلب اصلی

میان‌افزار سواگر (Swagger)

میان‌افزار Swagger مسئول ارائه مستندات API با استفاده از Swagger UI است.

هدف​

این میان‌افزار صفحه مستندات API تعاملی را ارائه می‌دهد و امکان تست APIها را فراهم می‌کند.

نحوه کار​

  1. بررسی فعال بودن Swagger در تنظیمات برنامه
  2. ارائه فایل‌های Swagger UI استاتیک
  3. تولید و ارائه فایل swagger.json
  4. مدیریت درخواست‌های Swagger UI

تنظیمات برنامه​

// در app.json یا metadata برنامه
{
  "swagger": {
    "enabled": true, // فعال بودن Swagger
    "path": "/docs"  // مسیر دسترسی به مستندات
  }
}

مسیرهای Swagger​

  • GET /docs: صفحه اصلی Swagger UI
  • GET /docs/swagger.json: فایل مشخصات OpenAPI
  • GET /docs/swagger-ui.css: فایل‌های استاتیک Swagger

ویژگی‌ها​

  • UI تعاملی: رابط کاربری برای مشاهده و تست APIها
  • OpenAPI 3.0: پشتیبانی از استاندارد OpenAPI
  • فایل‌های استاتیک: ارائه CSS و JS Swagger UI
  • یکپارچه‌سازی: استفاده از swagger-ui-dist

فعال‌سازی Swagger​

// در metadata برنامه
export const AppMetaData = {
  swagger: {
    enabled: true,
    path: "/api-docs"
  },
  // ... سایر تنظیمات
};

خطاها​

میان‌افزار در صورت غیرفعال بودن Swagger یا عدم وجود تنظیمات، درخواست را ادامه می‌دهد.