.NET Core - إضافة التوثيق باستخدام Swagger

5.4 .NET Core - إضافة التوثيق باستخدام Swagger

Swagger هو أداة قوية لتوليد واجهة تفاعلية لتوثيق وتجربة Web APIs في ASP.NET Core. يسمح لك بتجربة الـ endpoints، إدخال المعلمات، إرسال التوكن، ورؤية الرد مباشرة من المتصفح.

---

🔹 ما هو Swagger؟

Swagger (المعروف الآن باسم OpenAPI) يقوم بتوليد صفحة UI تفاعلية تمثل كل API endpoint في مشروعك، ويُستخدم أيضًا لتوليد مستندات JSON قابلة للاستيراد في Postman أو أدوات خارجية.

🔹 تثبيت حزمة Swashbuckle

dotnet add package Swashbuckle.AspNetCore

🔹 تهيئة Swagger في Program.cs

// في builder.Services
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// في app
app.UseSwagger();
app.UseSwaggerUI();

🔸 الآن عند تشغيل المشروع، انتقل إلى الرابط: /swagger مثل: https://localhost:5001/swagger

🔹 تخصيص عنوان التوثيق

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

🔹 حماية Swagger بـ JWT (إن وجد)

builder.Services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("Bearer", new()
    {
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "أدخل التوكن بهذا الشكل: Bearer <token>"
    });

    options.AddSecurityRequirement(new()
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new() { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
            },
            new List<string>()
        }
    });
});

🔸 بعد ذلك، سترى زر "Authorize" في واجهة Swagger لتجربة الـ APIs المحمية بـ JWT.

🔹 مزايا استخدام Swagger

• توثيق تلقائي لجميع الـ endpoints
• تجربة مباشرة لأي طلب بدون Postman
• يدعم إرسال Headers وJWT
• يمكن توليد ملفات OpenAPI/JSON لتصدير التوثيق

🔹 الخلاصة

Swagger أداة لا غنى عنها لأي Web API في .NET Core، خاصة في البيئات التشاركية أو أثناء اختبار المشروع. توفر لك وللفريق والمستهلكين واجهة منظمة لفهم الـ API وتجربته بدقة.