C# Academy · درس

إنشاء مستندات OpenAPI

أنشئوا مواصفات API قابلة للقراءة آليًا

إنشاء مستندات OpenAPI درس مجاني في C# Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في C# Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة C# Academy 4 دروس في المجموع.

ما هي OpenAPI؟

‏OpenAPI معيار لوصف واجهة API عبر HTTP وصفًا قابلًا للقراءة آليًا. ويمكنك من خلاله إنشاء الوثائق وحزم SDK للعملاء وأدوات الاختبار.

تتضمن .NET 9 إنشاء مستندات OpenAPI مدمجًا، ما يستغني عن الاعتماد الأقدم Swashbuckle في العديد من التطبيقات.

// OpenAPI document = JSON describing paths, schemas, params

حزمة Microsoft.AspNetCore.OpenApi

يوجد الدعم المدمج في Microsoft.AspNetCore.OpenApi. وتكون هذه الحزمة مضافة بالفعل في قوالب .NET 9.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

سجّل منشئ المستندات باستخدام AddOpenApi في تكوين الخدمات.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

تعرِض MapOpenApi المستند الذي تم إنشاؤه عبر نقطة نهاية. وتخدمه افتراضيًا على /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

تقييد العرض على بيئة التطوير

من الشائع عرض المستند في بيئة التطوير فقط، لتجنب كشف نطاق واجهتك في بيئة الإنتاج.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

وصف نقاط النهاية

تُستكمل بيانات OpenAPI الوصفية من التعليمات البرمجية. استخدم WithSummary وWithDescription وWithTags مع نقاط نهاية Minimal APIs.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

توثيق الاستجابات

صرّح بأنواع الاستجابات ورموز الحالة حتى يسرد المستند هذه المعلومات بدقة.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

محوّلات المستندات

خصّص المستند بأكمله - العنوان والإصدار والخوادم - باستخدام محوّل مستند تمرّره إلى AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

محوّلات العمليات

يعدّل محوّل العمليات العمليات الفردية - مثلًا، بإضافة معلمة ترويسة مشتركة إلى كل نقطة نهاية.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

إضافة واجهة مستخدم

ينشئ المنشئ المدمج مستند JSON، لكنه لا يوفر واجهة مستخدم. اقرنه بعارض مثل Scalar أو Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

الإنشاء في وقت البناء

يمكنك إنشاء ملف OpenAPI أثناء عملية البناء (من دون خادم قيد التشغيل) باستخدام أدوات Microsoft.Extensions.ApiDescription.Server، وهذا مفيد لإنشاء حزم العملاء في CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

تحقق سريع

تأكد من أساسيات OpenAPI في .NET 9.

مراجعة

لقد أنشأت مستندات OpenAPI:

تسجّل AddOpenApi() المنشئ، بينما تخدم MapOpenApi() ملف JSON.
أثرِ نقاط النهاية باستخدام WithSummary وProduces والعلامات.
تخصص محوّلات المستندات والعمليات المخرجات.
اقرنها مع Scalar أو Swagger UI للحصول على عرض تفاعلي.

التالي: توثيق واجهات API ذات الإصدارات.

الأسئلة الشائعة

هل درس «إنشاء مستندات OpenAPI» مجاني؟

نعم — نص درس «إنشاء مستندات OpenAPI» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة C# Academy، انتقل إلى CoddyKit PRO. تتضمن دورة C# Academy 4 دروس في المجموع.

ماذا ستتعلم في «إنشاء مستندات OpenAPI»؟

أنشئوا مواصفات API قابلة للقراءة آليًا تتمرن على C# Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ C# Academy؟

لا تُشترط خبرة سابقة. C# Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «إنشاء مستندات OpenAPI»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس C# Academy هذا؟

نعم. كل درس في C# Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى C# Academy