راهنمای کامل استفاده از Swagger با Asp.Net Core

در دنیای توسعه نرم‌افزار، ساخت APIهای قدرتمند تنها نیمی از مسیر است. نیم دیگر، ارائه مستنداتی شفاف، دقیق و قابل استفاده برای توسعه‌دهندگان دیگر است. بدون مستندات مناسب، بهترین APIها نیز بلااستفاده باقی می‌مانند. اینجاست که استفاده از Swagger با Asp.Net Core به یک ضرورت تبدیل می‌شود. 🚀Swagger (یا به عبارت دقیق‌تر، مشخصات OpenAPI) یک استاندارد صنعتی برای توصیف و مستندسازی APIهای RESTful است. این ابزار به شما اجازه می‌دهد تا به صورت خودکار، مستنداتی تعاملی و خوانا برای API خود ایجاد کنید. در این راهنمای جامع، ما قدم‌به‌قدم شما را با نصب، پیکربندی و بهینه‌سازی Swagger در پروژه‌های مدرن Asp.Net Core آشنا می‌کنیم.

Swagger چیست و چرا برای APIهای Asp.Net Core ضروری است؟

تصور کنید یک نقشه گنج دارید، اما هیچ راهنمایی برای خواندن آن وجود ندارد. API شما همان گنج است و Swagger نقشه راه آن. Swagger با استفاده از یک فایل JSON یا YAML، تمام End-pointها، متدها (GET, POST, …)، پارامترهای ورودی و مدل‌های خروجی API شما را توصیف می‌کند.

کتابخانه Swashbuckle.AspNetCore محبوب‌ترین پیاده‌سازی Swagger برای Asp.Net Core است. این کتابخانه به طور خودکار ساختار API شما را تحلیل کرده و مستندات Swagger را تولید می‌کند. در نتیجه، شما یک رابط کاربری زیبا (Swagger UI) در اختیار خواهید داشت که به کمک آن می‌توانید:

لیست تمام End-pointها را مشاهده کنید.
اطلاعات دقیق هر End-point را بررسی کنید.
API را به صورت مستقیم از طریق مرورگر تست کنید.

مزایای کلیدی استفاده از Swagger در پروژه شما

ادغام Swagger در پروژه Asp.Net Core شما مزایای چشمگیری به همراه دارد که فراتر از یک مستندسازی ساده است. این ابزار بهره‌وری تیم شما را به شکل قابل توجهی افزایش می‌دهد.

✅ مستندسازی خودکار: با هر تغییری در کد، مستندات شما به صورت خودکار به‌روز می‌شوند. این ویژگی شما را از نگهداری دستی مستندات نجات می‌دهد.
🧠 کاهش خطاهای انسانی: مستندات همیشه با کد واقعی شما همگام هستند. بنابراین، احتمال بروز خطا به دلیل اطلاعات قدیمی کاهش می‌یابد.
🤝 همکاری تیمی بهتر: تیم‌های Frontend و Backend می‌توانند به طور موازی کار کنند. تیم Frontend دیگر منتظر تکمیل API نمی‌ماند و از مستندات برای توسعه استفاده می‌کند.
⚡️ تست و عیب‌یابی سریع: با رابط کاربری تعاملی Swagger، می‌توانید End-pointها را بدون نیاز به ابزارهای جانبی مانند Postman به سرعت تست و بررسی کنید.
📚 شفافیت و درک آسان: توسعه‌دهندگان جدید به سرعت می‌توانند ساختار و عملکرد API شما را درک کرده و کار خود را شروع کنند.

راهنمای گام‌به‌گام نصب و پیکربندی Swagger با Asp.Net Core

حالا بیایید به بخش عملی ماجرا بپردازیم. راه‌اندازی Swagger در پروژه‌های مدرن .NET (نسخه‌های 6 و بالاتر) بسیار ساده و سریع است.

قدم اول: نصب پکیج Swashbuckle.AspNetCore

ابتدا، باید پکیج نوگت Swashbuckle را به پروژه خود اضافه کنید. ترمینال را در مسیر پروژه باز کرده و دستور زیر را اجرا کنید:

bash

dotnet add package Swashbuckle.AspNetCore

یا اگر از Package Manager Console در ویژوال استودیو استفاده می‌کنید:

bash

Install-Package Swashbuckle.AspNetCore

قدم دوم: پیکربندی سرویس‌های Swagger در Program.cs

در پروژه‌های مدرن .NET، فایل Startup.cs حذف شده و تمام تنظیمات در فایل Program.cs انجام می‌شود. کدهای زیر را به این فایل اضافه کنید.

csharp

var builder = WebApplication.CreateBuilder(args);

// 1. سرویس‌های کنترلر را اضافه کنید
builder.Services.AddControllers();

// 2. سرویس‌های مورد نیاز Swagger را اضافه کنید
builder.Services.AddEndpointsApiExplorer(); // این سرویس برای شناسایی End-pointها ضروری است
builder.Services.AddSwaggerGen();

var app = builder.Build();

این دو خط کد، تمام سرویس‌های لازم برای تولید مستندات OpenAPI را به پروژه شما اضافه می‌کنند.

قدم سوم: فعال‌سازی UI در Middleware Pipeline

در نهایت، باید به برنامه بگویید که از Swagger و رابط کاربری آن استفاده کند. کد زیر را به فایل Program.cs، قبل از خط app.Run() اضافه کنید.

csharp

// ... کدهای قبلی

var app = builder.Build();

// 3. Swagger را فقط در محیط توسعه فعال کنید
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

نکته مهم: فعال‌سازی Swagger UI در محیط Production توصیه نمی‌شود، زیرا ساختار داخلی API شما را افشا می‌کند.

حالا پروژه را اجرا کنید (dotnet run). سپس به آدرس https://localhost:{yourport}/swagger بروید. شما باید رابط کاربری زیبا و تعاملی Swagger را ببینید. 🤩 راهنمای کامل استفاده از Swagger با Asp.Net Core

غنی‌سازی مستندات API با کامنت‌های XML

مستندات پیش‌فرض Swagger عالی هستند، اما شما می‌توانید با افزودن توضیحات سفارشی از طریق کامنت‌های XML، آن‌ها را بسیار غنی‌تر و مفیدتر کنید.

فعال‌سازی تولید فایل XML

ابتدا باید به پروژه خود بگویید که یک فایل XML از کامنت‌های کد شما تولید کند. فایل .csproj پروژه خود را باز کرده و خط زیر را درون تگ <PropertyGroup> اضافه کنید:

xml

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

خط <NoWarn> هشدارهای مربوط به متدهای بدون کامنت را غیرفعال می‌کند.

اتصال فایل XML به Swagger

حالا به فایل Program.cs برگردید و پیکربندی AddSwaggerGen را به شکل زیر تغییر دهید تا فایل XML تولید شده را بخواند.

csharp

using System.Reflection;

// ...

builder.Services.AddSwaggerGen(options =>
{
    // دریافت مسیر فایل XML تولید شده
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

حالا می‌توانید با استفاده از کامنت‌های سه‌گانه (///)، End-pointها و پارامترهای خود را توضیح دهید.

csharp

/// <summary>
/// یک آیتم خاص را بر اساس شناسه دریافت می‌کند.
/// </summary>
/// <param name="id">شناسه آیتم مورد نظر</param>
/// <response code="200">آیتم با موفقیت بازگردانده شد.</response>
/// <response code="404">اگر آیتم با شناسه مورد نظر یافت نشود.</response>
[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<string> Get(int id)
{
    if (id <= 0)
    {
        return NotFound();
    }
    return Ok($"value {id}");
}

این توضیحات به طور خودکار در رابط کاربری Swagger نمایش داده می‌شوند.

کاربردهای عملی Swagger در توسعه API

Swagger فقط برای نمایش مستندات نیست. این ابزار در چرخه‌های مختلف توسعه کاربردهای فراوانی دارد.

🧪 تست سریع End-pointها: به جای استفاده از ابزارهای دیگر، می‌توانید درخواست‌ها را با پارامترهای مختلف مستقیماً از Swagger UI ارسال کرده و پاسخ را مشاهده کنید.
🧑‍💻 آنبوردینگ توسعه‌دهندگان جدید: اعضای جدید تیم می‌توانند به سرعت با API آشنا شوند، بدون اینکه نیاز به پرسش‌های مکرر داشته باشند.
⚙️ تولید خودکار کد کلاینت (Client Generation): ابزارهای زیادی وجود دارند که می‌توانند از فایل swagger.json شما برای تولید خودکار کدهای سمت کلاینت در زبان‌های مختلف (مانند TypeScript, Java, Python) استفاده کنند.
📄 مرجع اصلی حقیقت (Single Source of Truth): مستندات Swagger به عنوان منبع اصلی و قابل اعتماد برای تمام تیم‌ها (Frontend, Mobile, QA) عمل می‌کند.

ثبت‌نام و دریافت کلید API

بسیاری از APIها برای استفاده نیاز به احراز هویت و کلید API دارند. اگر سرویس شما نیز چنین نیازی دارد، می‌توانید کاربران را به ثبت‌نام و دریافت کلید راهنمایی کنید. مراحل ثبت‌نام در سرویس ما بسیار ساده است:

به پورتال توسعه‌دهندگان ما در p.api.ir مراجعه کنید.
با استفاده از ایمیل خود یک حساب کاربری جدید ایجاد نمایید.
پس از ورود، از بخش «کلیدهای API» می‌توانید کلید اختصاصی خود را تولید و کپی کنید.

سپس می‌توانید از این کلید برای احراز هویت در درخواست‌های خود استفاده نمایید.

Swagger، ابزاری فراتر از یک مستندساز

همانطور که دیدید، استفاده از Swagger با Asp.Net Core یک انتخاب هوشمندانه برای هر پروژه API محور است. این ابزار قدرتمند نه تنها فرآیند مستندسازی را خودکار و لذت‌بخش می‌کند، بلکه به عنوان یک پل ارتباطی میان تیم‌های مختلف عمل کرده و سرعت و کیفیت توسعه را به طور چشمگیری افزایش می‌دهد. سرمایه‌گذاری زمان برای راه‌اندازی صحیح آن، در طول عمر پروژه بارها به شما باز خواهد گشت. ✨

شما از چه ابزارهای دیگری برای مستندسازی و تست APIهای خود استفاده می‌کنید؟ نظرات و تجربیات خود را در بخش دیدگاه‌ها با ما به اشتراک بگذارید.