C# Geeks (.NET) on Telegram: “ءSwagger در NET 10. حذف شده؟ چطور دوباره اضافه‌ا…”

ءSwagger در NET 10. حذف شده؟ چطور دوباره اضافه‌اش کنیم 🔍

شما یک پروژه‌ی NET 10. می‌سازید، برنامه را اجرا می‌کنید، تلاش می‌کنید صفحه‌ی Swagger را باز کنید، و با خطای 404 Not Found مواجه می‌شوید. ❌
پس چطور باید آن را برگردانیم؟

چرا Swagger حذف شده است؟ 🤔

مایکروسافت پشتیبانی از Swagger را از NET 9. حذف کرده است. طبق این بحث در GitHub:

"The project is no longer actively maintained by its community owner. Issues have not been addressed or resolved..."

یعنی:
این پروژه دیگر به‌صورت فعال توسط مالک جامعه‌ی آن نگهداری نمی‌شود. مشکلات بررسی یا حل نشده‌اند.

مایکروسافت به سمت استفاده از OpenAPI حرکت کرده است، یعنی حالا مستندات OpenAPI می‌توانند بدون نیاز به Swagger تولید شوند. 📄

چطور Swagger را به NET 10. اضافه کنیم 🛠

ابتدا باید پکیج زیر را به پروژه‌ی Web API خود اضافه کنید:

Swashbuckle.AspNetCore.SwaggerUI

سپس داخل فایل Program.cs باید پارامتر options را به متد UseSwaggerUI اضافه کنید و endpoint را روی /openapi/v1.json تنظیم کنید.

// Program.cs
if (app.Environment.IsDevelopment())
{
  app.MapOpenApi();

  // Add this
  app.UseSwaggerUI(options =>
  {
    options.SwaggerEndpoint("/openapi/v1.json", "API v1");
  });
}

اجرای خودکار Swagger هنگام اجرا 🚀

اگر می‌خواهید برنامه هنگام اجرا به‌صورت خودکار با Swagger باز شود، به مسیر زیر بروید:
Properties > launchSettings.json

پروفایل https را پیدا کنید، مقدار launchBrowser را برابر true قرار دهید و launchUrl را روی swagger تنظیم کنید.

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5155",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:7284;http://localhost:5155",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

جایگزین‌های Swagger 🔄

ءSwagger دوباره اضافه شده، اما آیا جایگزین‌های بهتری وجود دارند؟

Scalar ✨

ءScalar یک جایگزین برای Swagger است. این ابزار به شما اجازه می‌دهد endpointها را با یک رابط کاربری متفاوت تست کنید.

برای اضافه کردن Scalar، پکیج Scalar.AspNetCore را در پروژه‌ی Web API خود نصب کنید.

سپس، در فایل Program.cs، فضای نام Scalar.AspNetCore را import کنید و کد زیر را اضافه کنید:

// Program.cs
using Scalar.AspNetCore; // <-- Import this namespace

...

if (app.Environment.IsDevelopment()) 
{
  app.MapOpenApi();
  app.MapScalarApiReference(); // <-- Add this line
}

برای اجرای برنامه همراه با Scalar، فایل launchSettings.json را باز کنید.

مقدار launchBrowser را روی true بگذارید و launchUrl را برابر scalar/v1 تنظیم کنید.

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5155",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "scalar/v1",
      "applicationUrl": "https://localhost:7284;http://localhost:5155",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

همچنین می‌توانید تنظیمات Scalar را شخصی‌سازی کنید. در این مثال، عنوان روی "My API" تنظیم شده، تم برابر با ScalarTheme.Mars است و نوار کناری مخفی شده است.

// Program.cs
if (app.Environment.IsDevelopment()) 
{
  app.MapOpenApi();
  app.MapScalarApiReference(options => 
  {
    options.WithTitle("My API");
    options.WithTheme(ScalarTheme.Mars);
    options.HideSidebar();
  });
}