توليد Swagger/OpenAPI لـ C# (.NET): Swashbuckle و NSwag

توليد Swagger/OpenAPI لـ C# (.NET): Swashbuckle و NSwag

توثيق REST API هو جزء لا يتجزأ من التطوير الحديث باستخدام C# (.NET). تسمح مواصفة OpenAPI (المعروفة سابقًا باسم Swagger) بوصف نقاط النهاية، نماذج البيانات، المعاملات والاستجابات بتنسيق واحد قابل للقراءة آليًا (JSON/YAML). في نظام .NET Core / .NET 5+، توجد أداتان رئيسيتان للتوليد التلقائي لمواصفة OpenAPI: Swashbuckle.AspNetCore و NSwag. تتكامل كلتا الأداتين مع ASP.NET Core، وتحللان الكود الخاص بك وتنشئان توثيقًا تفاعليًا (Swagger UI).

Swashbuckle.AspNetCore: الخيار الكلاسيكي

Swashbuckle هي الحزمة الأكثر شيوعًا لتوليد Swagger/OpenAPI في .NET. تقوم ببناء المواصفة تلقائيًا بناءً على المتحكمات، سمات التوجيه والتعليقات التوضيحية للنماذج. تدعم OpenAPI 3.0 و Swagger 2.0.

التثبيت والإعداد الأساسي

dotnet add package Swashbuckle.AspNetCore

في ملف Program.cs (أو Startup.cs للإصدارات القديمة)، أضف الخدمات والوسيطة:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "واجهة برمجة التطبيقات الخاصة بي",        Version = "v1",        Description = "مثال على API لموقع تعليمي"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "واجهة برمجة التطبيقات الخاصة بي v1");    });}

app.MapControllers();app.Run();

بعد التشغيل، انتقل إلى العنوان /swagger - ستفتح واجهة مستخدم تفاعلية حيث يمكنك اختبار نقاط النهاية مباشرة من المتصفح.

إضافة تعليقات XML

لكي تظهر الأوصاف من تعليقات XML في التوثيق، قم بتفعيل توليد ملف XML في .csproj:

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

ثم حدد المسار إلى ملف XML في AddSwaggerGen:

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

الآن ستظهر التعليقات من الكود في Swagger UI.

مثال على متحكم مع تعليقات توضيحية

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// الحصول على قائمة بجميع المنتجات    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// الحصول على منتج حسب المعرف    /// </summary>    /// <param name="id">معرف المنتج</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "مثال" });    }}

NSwag: أداة متعددة الاستخدامات مع توليد العملاء

NSwag هو بديل أكثر قوة. بالإضافة إلى توليد التوثيق، يمكنه إنشاء عملاء C# لواجهة API، عملاء TypeScript، وكذلك توليد كود بناءً على مواصفات OpenAPI الخارجية.

التثبيت والإعداد

dotnet add package NSwag.AspNetCore

الإعداد في Program.cs:

builder.Services.AddOpenApiDocument(config =>{    config.Title = "واجهة برمجة التطبيقات الخاصة بي (NSwag)";    config.Version = "v1";    config.Description = "API تم توليده باستخدام NSwag";});

// ...