Swagger/OpenAPI لـ C# (.NET): إنشاء وتوثيق API

إنشاء Swagger/OpenAPI لـ C# (.NET)

\n\n

Swagger (المعروف رسميًا الآن باسم OpenAPI) هو أداة قوية لتصميم وإنشاء وتوثيق واستخدام RESTful API. في نظام .NET البيئي، أصبح إنشاء مواصفات OpenAPI والتوثيق التفاعلي جزءًا لا يتجزأ من تطوير خدمات الويب الحديثة. في هذه المقالة، سنستعرض بالتفصيل كيفية إعداد الإنشاء التلقائي لـ Swagger/OpenAPI في تطبيقات C# (.NET) باستخدام مكتبة Swashbuckle.AspNetCore.

\n\n

يتيح Swagger ليس فقط إنشاء توثيق قابل للقراءة تلقائيًا، بل يوفر أيضًا واجهة تفاعلية (Swagger UI) لاختبار نقاط النهاية مباشرة من المتصفح. هذا يسرع بشكل كبير عملية التطوير والتكامل بين الفرق.

\n\n

تثبيت وإعداد Swashbuckle في .NET

\n\n

للبدء، نحتاج إلى تثبيت الحزمة Swashbuckle.AspNetCore. هذه هي الحزمة الرئيسية التي تتضمن مولد Swagger وواجهة Swagger UI والتكامل مع ASP.NET Core.

\n\n

التثبيت عبر NuGet Package Manager Console:

\n

Install-Package Swashbuckle.AspNetCore

\n\n

أو عبر .NET CLI:

\n

dotnet add package Swashbuckle.AspNetCore

\n\n

بعد تثبيت الحزمة، يجب إعداد الخدمات في ملف Program.cs (أو Startup.cs للإصدارات الأقدم). دعنا نلقي نظرة على التكوين الأدنى لـ .NET 8 والإصدارات الأحدث:

\n\n

var builder = WebApplication.CreateBuilder(args);\n\n// إضافة خدمات Swagger\nbuilder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo\n    {\n        Title = "My API",\n        Version = "v1",\n        Description = "مثال على API مع توثيق Swagger"\n    });\n});\n\nbuilder.Services.AddControllers();\n\nvar app = builder.Build();\n\nif (app.Environment.IsDevelopment())\n{\n    app.UseSwagger();\n    app.UseSwaggerUI(c =>\n    {\n        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");\n    });\n}\n\napp.UseHttpsRedirection();\napp.MapControllers();\n\napp.Run();

\n\n

الميزات الرئيسية لـ Swashbuckle

\n\n

\n
• الإنشاء التلقائي لمواصفات OpenAPI — تقوم المكتبة بتحليل وحدات التحكم ونماذج البيانات والسمات الخاصة بك، لإنشاء ملف مواصفات بتنسيق JSON/YAML.
\n
• واجهة Swagger UI التفاعلية — واجهة ويب يمكنك من خلالها عرض نقاط النهاية وإرسال الطلبات ورؤية الردود.
\n
• دعم تعليقات XML — إذا أضفت توثيق XML لوحدات التحكم والنماذج الخاصة بك، سيعرضها Swagger في الواجهة.
\n
• التجميع حسب الإصدارات — يمكنك إنشاء إصدارات متعددة من التوثيق لإصدارات مختلفة من API.
\n
• التخصيص — إمكانية تخصيص المظهر وإضافة الرؤوس ومخططات المصادقة (JWT, Basic Auth) وغير ذلك الكثير.
\n

\n\n

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

\n\n

لجعل توثيقك غنيًا بالمعلومات، استخدم تعليقات XML. أولاً، قم بتمكين إنشاء ملف XML في المشروع. افتح ملف .csproj وأضف:

\n\n

<PropertyGroup>\n    <GenerateDocumentationFile>true</GenerateDocumentationFile>\n    <NoWarn>$(NoWarn);1591</NoWarn>\n</PropertyGroup>

\n\n

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

\n\n

builder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });\n    \n    // تحديد المسار إلى ملف XML للتوثيق\n    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";\n    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\n    c.IncludeXmlComments(xmlPath);\n});

\n\n

الآن ستظهر التعليقات من الكود الخاص بك في Swagger UI. مثال على وحدة تحكم مع تعليقات:

\n\n

/// <summary>\n