.NET API - توثيق الـAPI باستخدام Swagger

2.4 ‎.NET API - توثيق الـAPI باستخدام Swagger

Swagger هو أداة لتوثيق واختبار واجهات الـ Web API، وتُعرف الآن باسم OpenAPI. يتم دمجها بسهولة مع ASP.NET Core Web API لتوليد صفحة توثيق تفاعلية لكل الـEndpoints.

⚙️ 1. تثبيت الحزمة (إذا لم تكن موجودة)

عادة ما تكون موجودة تلقائيًا عند إنشاء مشروع Web API جديد، لكن يمكنك تثبيتها يدويًا:

dotnet add package Swashbuckle.AspNetCore

🧠 2. تفعيل Swagger في Program.cs

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

🌐 3. الدخول إلى واجهة Swagger

بعد تشغيل المشروع، افتح الرابط التالي في المتصفح:

http://localhost:5000/swagger

ستظهر صفحة تحتوي على كل الـControllers وEndpoints، ويمكنك تجربة أي طلب منها مباشرة.

📝 4. إضافة تعليقات XML لتفاصيل التوثيق

من داخل خصائص المشروع، فعّل خيار XML documentation file

ثم أضف التعليق فوق كل دالة:

/// <summary>
/// يُرجع جميع المنتجات.
/// </summary>
[HttpGet]
public IActionResult GetAll() => Ok(_context.Products.ToList());

ثم أضف التالي في Program.cs لتضمين ملف XML:

builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

🔐 5. دعم التوثيق مع المصادقة (JWT)

يمكنك إعداد Swagger لطلب التوكن JWT لإجراء التجارب المحمية:

builder.Services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "أدخل 'Bearer' متبوعًا بالتوكن."
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type=ReferenceType.SecurityScheme,
                    Id="Bearer"
                }
            },
            new string[]{}
        }
    });
});

📌 ملاحظات سريعة

• ✅ Swagger مفيد أثناء التطوير والاختبار.
• ✅ يمكنك حفظ التوثيق وتصديره بصيغة JSON أو YAML.
• ✅ يمكن تعطيله في بيئة الإنتاج لحماية النظام.