Swashbuckle C# (.NET): طرق، أمثلة، تثبيت

ما هو Swashbuckle ولماذا تحتاجه؟

Swashbuckle هي مكتبة قوية لمنصة .NET تقوم تلقائيًا بإنشاء توثيق تفاعلي لواجهات برمجة التطبيقات (Web API) الخاصة بك بناءً على معيار OpenAPI (المعروف سابقًا باسم Swagger). تتكامل المكتبة مباشرة مع تطبيقات ASP.NET Core وتتيح للمطورين والمختبرين ومستهلكي API فهم نقاط النهاية الخاصة بك والتفاعل معها بسهولة.

لماذا تحتاج إلى Swashbuckle؟

أتمتة التوثيق: لن تحتاج بعد الآن إلى كتابة وتحديث التوثيق يدويًا. يقوم Swashbuckle بتحليل المتحكمات (Controllers) والنماذج والخصائص الخاصة بك لإنشاء توثيق محدث تلقائيًا.
واجهة تفاعلية (Swagger UI): توفر المكتبة واجهة ويب يمكنك من خلالها استعراض جميع نقاط النهاية ومعاملاتها ونماذج البيانات، بل وحتى تنفيذ طلبات اختبارية مباشرة من المتصفح.
التوحيد القياسي: OpenAPI هو المعيار الصناعي المعتمد. يمكن استخدام التوثيق المُنشأ لتوليد حزم تطوير برمجية (SDKs) بلغات مختلفة مثل JavaScript وPython وJava وغيرها.
تبسيط الاختبار وتصحيح الأخطاء: يمكن للمطورين ومهندسي ضمان الجودة اختبار API بسرعة دون الحاجة إلى أدوات خارجية مثل Postman (على الرغم من أن Postman يمكنه أيضًا استيراد مواصفات OpenAPI).

يتكون Swashbuckle من مكونين رئيسيين: Swashbuckle.AspNetCore.Swagger (لإنشاء مواصفات OpenAPI بصيغة JSON) و Swashbuckle.AspNetCore.SwaggerUI (لعرض الواجهة التفاعلية).

طريقة التثبيت

يتم تثبيت Swashbuckle عبر مدير الحزم NuGet. يمكنك استخدام وحدة تحكم مدير الحزم، أو .NET CLI، أو واجهة Visual Studio.

عبر .NET CLI (موصى به)

dotnet add package Swashbuckle.AspNetCore

عبر Package Manager Console في Visual Studio

Install-Package Swashbuckle.AspNetCore

سيقوم هذا الأمر بتثبيت الحزمة الرئيسية التي تتضمن جميع المكونات الضرورية: Swagger و SwaggerUI و Swashbuckle.Core.

بداية سريعة مع مثال عملي

دعنا نستعرض الحد الأدنى من الإعدادات لتشغيل Swashbuckle في مشروع ASP.NET Core Web API.

1. إنشاء مشروع Web API جديد

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. إضافة Swashbuckle

dotnet add package Swashbuckle.AspNetCore

3. إعداد ملف Program.cs

افتح ملف Program.cs وأضف الأسطر التالية:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// إضافة خدمات Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Awesome API",
        Version = "v1",
        Description = "مثال على API لتوضيح استخدام Swashbuckle"
    });
});

var app = builder.Build();

// تفعيل middleware الخاص بـ Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// مثال على نقطة نهاية بسيطة
var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}