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

مستندسازی API یکی از حیاتی‌ترین بخش‌های توسعه نرم‌افزار است. توسعه‌دهندگان برای تعامل با سرویس‌ها به راهنمای دقیق نیاز دارند. ابزار Swagger (OpenAPI) این فرآیند را کاملاً خودکار می‌کند. این ابزار محیطی تعاملی برای تست و مشاهده ای‌پی‌آی‌ها فراهم می‌سازد. در این مقاله، نحوه استفاده از Swagger با Asp.Net Core را بررسی می‌کنیم. 🚀

چرا باید از Swagger استفاده کنیم؟

استفاده از این ابزار مزایای بی‌شماری برای تیم‌های فنی دارد. این ابزار نه تنها داکیومنت می‌سازد، بلکه محیط تست زنده فراهم می‌آورد.

✅ مزایای اصلی Swagger

• 💠 تولید خودکار مستندات بدون نیاز به نوشتن دستی.
• 💠 امکان تست متدهای API در محیط مرورگر.
• 💠 کاهش خطاهای انسانی در زمان فراخوانی سرویس‌ها.
• 💠 هماهنگی کامل با استانداردهای OpenAPI.
• 💠 قابلیت شخصی‌سازی بالا برای نیازهای خاص پروژه.
• 💠 فهم بهتر ساختار داده‌ها توسط توسعه‌دهندگان فرانت‌اند.

🛠 کاربردهای عملی

• 💠 استفاده در پروژه‌های بزرگ با تعداد اندپوینت زیاد.
• 💠 ارائه مستندات به مشتریان خارجی (Third-party).
• 💠 یکپارچه‌سازی سریع‌تر تیم‌های بک‌باند و فرانت‌اند.
• 💠 عیب‌یابی سریع پارامترهای ورودی و خروجی.

آموزش نصب و راه‌اندازی Swagger

برای شروع، باید پکیج مورد نظر را نصب کنید. نام این کتابخانه محبوب Swashbuckle.AspNetCore است. شما می‌توانید از طریق کنسول مدیریت پکیج، دستور زیر را اجرا کنید:

Install-Package Swashbuckle.AspNetCore

پس از نصب، نوبت به پیکربندی در پروژه می‌رسد. در نسخه‌های جدید دات‌نت، این تنظیمات در فایل Program.cs انجام می‌شود. 💻

مرحله اول: ثبت سرویس Swagger

در فایل تنظیمات خود، کد زیر را برای شناسایی سرویس اضافه کنید:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

مرحله دوم: فعال‌سازی Middleware

باید به اپلیکیشن بگویید که از رابط کاربری سواگر استفاده کند. کدهای زیر را در بخش مربوطه قرار دهید:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

حالا پروژه را اجرا کنید. به آدرس /swagger در مرورگر بروید. اکنون باید لیست تمام APIهای خود را مشاهده کنید. 🔎

شخصی‌سازی پیشرفته و تنظیمات خاص

گاهی نیاز دارید داده‌ها را به شکل خاصی نمایش دهید. مثلاً تبدیل تمامی Enumها به رشته یا استفاده از CamelCase. برای این کار، در متد AddSwaggerGen تغییرات زیر را اعمال کنید:

services.AddSwaggerGen(swagger =>
{
    swagger.DescribeAllParametersInCamelCase();
    swagger.SwaggerDoc("v1", new Info { Title = "Professional API" });
});

این تنظیمات باعث خوانایی بیشتر مستندات شما می‌شود. همچنین می‌توانید اطلاعات نویسنده و لایسنس پروژه را در بخش Info اضافه نمایید. ✨

آموزش ثبت‌نام در سیستم مدیریت API

برای مدیریت بهتر پروژه‌های خود، ثبت‌نام در پنل‌های تخصصی الزامی است. این کار باعث دسترسی به ابزارهای پیشرفته‌تر می‌شود. مراحل زیر را دنبال کنید:

۱. 🌐 ابتدا وارد وب‌سایت p.api.ir شوید.

۲. 📝 فرم ثبت‌نام را با اطلاعات هویتی تکمیل کنید.

۳. 📧 ایمیل تایید ارسال شده را فعال نمایید.

۴. 🔑 کلید اختصاصی API خود را دریافت کنید.

ثبت‌نام در این سامانه فرآیند توسعه شما را تسریع می‌کند. حتماً از لینک p.api.ir برای شروع استفاده کنید. 🔗

قدرت‌نمایی با کامنت‌های XML

توضیحات خودکار عالی هستند اما کافی نیستند. گاهی نیاز به توضیحات متنی دقیق برای هر پارامتر دارید. کامنت‌های XML در سی‌شارپ بهترین راهکار هستند.

ابتدا باید تولید فایل XML را در تنظیمات پروژه فعال کنید. روی پروژه راست‌کلیک کرده و به بخش Properties بروید. در تب Build، گزینه Documentation File را تیک بزنید.

سپس در کد خود از الگوی زیر استفاده کنید:

/// <summary>
/// دریافت اطلاعات کاربر بر اساس شناسه
/// </summary>
/// <param name="id">شناسه عددی کاربر</param>
[HttpGet("{id}")]
public IActionResult GetUser(int id) => Ok();

در نهایت، سواگر را مطلع کنید که این فایل را بخواند:

var xmlPath = Path.Combine(AppContext.BaseDirectory, "YourApp.xml");
options.IncludeXmlComments(xmlPath);

مدیریت کدهای وضعیت (Response Codes)

یک API حرفه‌ای باید تمام پاسخ‌های ممکن را نمایش دهد. پاسخ ۲۰Success ،۴۰۴NotFound یا ۴۰۰BadRequest باید مستند شوند. برای این کار از Attributeهای مخصوص استفاده می‌کنیم:

[HttpGet("{id}")]
[ProducesResponseType(typeof(UserDto), 200)]
[ProducesResponseType(404)]
public IActionResult Get(int id)
{
    // کدهای مربوط به دریافت داده
}

با این کار، توسعه‌دهنده متوجه می‌شود در هر شرایطی چه خروجی‌ای دریافت می‌کند. این موضوع شفافیت پروژه را دوچندان می‌کند. 📊

عیب‌یابی و رفع مشکلات رایج

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

۱. صفحه سواگر نمایش داده نمی‌شود

ابتدا پکیج Microsoft.AspNetCore.StaticFiles را بررسی کنید. این پکیج باید به درستی نصب شده باشد. بدون فایل‌های استاتیک، رابط کاربری لود نمی‌شود. 🛠

۲. استفاده از MvcCore

اگر از AddMvcCore استفاده می‌کنید، سواگر به صورت خودکار کار نمی‌کند. باید سرویس ApiExplorer را به صورت دستی اضافه کنید:

services.AddMvcCore().AddApiExplorer();

۳. مشکل در مسیردهی (Routing)

سواگر به شدت به Attribute Routing وابسته است. اگر از مسیردهی سنتی استفاده کنید، متدها شناسایی نمی‌شوند. حتماً بالای هر اکشن از [Route] یا [HttpGet] استفاده کنید.

خلاصه کلام

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

نظر شما چیست؟ آیا در پیاده‌سازی سواگر با چالشی روبرو شده‌اید؟ سوالات خود را در بخش نظرات بپرسید تا کارشناسان ما پاسخگوی شما باشند.