التوثيق مع المكتبات الخارجية

يعد استخدام مكتبات متعددة لتقسيم التعليمات البرمجية الخاصة بك للحالات المستقبلية أمرًا جيدًا. أنا شخصياً أحب القيام بذلك، إذا كان بإمكاني تقسيم المنطق الخاص بي بحيث يمكن إعادة استخدامه في مشاريع أخرى أو أجزاء من المشاريع.

بالنسبة لي على الأقل، من الضروري تقسيم نماذج البيانات، التي تتضمن Entity Framework، بحيث يمكن الرجوع إليها واستخدامها في Console application، أو Blazor application أو API.

دعونا نلقي نظرة على مثال لكيفية القيام بالأشياء، هذه لقطة شاشة لمشروع يحتوي على عدد قليل من التطبيقات ومكتبة مشتركة تحتوي على جميع النماذج.

هذا مثال على فصل قمت بنقله من مشروع API مع وثائق تحتوي على summary لكل خاصية وفئة.

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

إذا أشرنا إلى Console application وبدأنا في استخدام النموذج، فيمكننا رؤية الوثائق، وهي ميزة قياسية في Visual Studio لذا فهي تعمل بشكل جيد، كما ترون هنا:

ولكن بعد ذلك، إذا أشرنا إلى API وانتقلنا إلى Swagger، فلن يكون هناك توثيق موجز.

كيف نصلح هذا؟

أولاً، علينا تمكين تعليقات XML على المكتبة، وللقيام بذلك، تحتاج إلى تحديث إعدادات المشاريع وتمكين ``:

سيؤدي هذا إلى إنشاء بعض الملفات في مجلد البناء والتي تنتهي بامتداد الملف xml، كما ترون هنا:

الآن بعد أن انتهينا من ذلك، يتعين علينا إضافة بعض العناصر على Program.cs، من أجل التبختر في قراءة تلك الملفات، وذلك لأنه بشكل افتراضي يقوم فقط بتحميل تعريف XML للمشروع الذي يعمل عليه.

يستخدم طريقة موجودة داخل AddSwaggerGen تسمى IncludeXmlComments.

الفكرة هي أنه إذا كان لدينا جميع ملفات xml، فسنضطر إلى تحميلها على Swagger.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

لقد تم توجيهها مباشرة، نحصل على ملفات xml من دليل البناء ونضيفها باستخدام طريقة IncludeXmlComments.

الآن نقوم بتحميل API مرة أخرى ونتحقق مما إذا كان بإمكاننا رؤية الوثائق.

ويمكنك أن ترى أنه يمكننا رؤية الوثائق!

آمل أن يكون قد ساعدك، إذا كان لديك أي سؤال فلا تتردد في الاتصال بي!