เอกสาร Xml สำหรับ Web Api จะรวมเอกสารจากนอกเหนือจากโครงการหลักได้อย่างไร

เอกสารสำหรับการเปิดใช้บูรณาการ XMLDOC เป็นโครงการ Api เว็บของคุณจะปรากฏขึ้นเพื่อสถานการณ์ที่จับเฉพาะที่ทุกประเภท API ของคุณเป็นส่วนหนึ่งของโครงการ WebAPI ของคุณ โดยเฉพาะอย่างยิ่งจะกล่าวถึงวิธีการกำหนดเส้นทางเอกสาร XML ใหม่App_Data/XmlDocument.xmlและการยกเลิกการใส่เครื่องหมายบรรทัดใน config ของคุณที่จะใช้ไฟล์นั้น โดยปริยายนี้อนุญาตให้ใช้ไฟล์เอกสารของโครงการเดียวเท่านั้น

อย่างไรก็ตามในการตั้งค่าของฉันฉันมีคำขอและประเภทการตอบกลับที่กำหนดไว้ในโครงการ "โมเดล" ทั่วไป ซึ่งหมายความว่าหากฉันมีจุดสิ้นสุดที่กำหนดไว้เช่น:

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

ที่OpenIdLoginRequestกำหนดไว้ในโครงการ C # แยกต่างหากดังนี้:

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

แม้จะมีเอกสาร XML แต่คุณสมบัติของrequestพารามิเตอร์จะไม่มีเอกสารประกอบเมื่อคุณดูเพจวิธีใช้เฉพาะปลายทาง (เช่นhttp://localhost/Help/Api/POST-auth-openid-login)

ฉันจะสร้างประเภทในโครงการย่อยที่มีเอกสาร XML ปรากฏในเอกสาร Web API XML ได้อย่างไร

ไม่มีวิธีในตัวเพื่อให้บรรลุเป้าหมายนี้ อย่างไรก็ตามต้องใช้เพียงไม่กี่ขั้นตอน:

1. เปิดใช้งานเอกสาร XML สำหรับโปรเจ็กต์ย่อยของคุณ (จากคุณสมบัติโปรเจ็กต์ / บิลด์) เช่นเดียวกับที่คุณมีสำหรับโปรเจ็กต์ Web API ของคุณ ยกเว้นเวลานี้กำหนดเส้นทางโดยตรงเพื่อXmlDocument.xmlให้สร้างขึ้นในโฟลเดอร์รูทของโปรเจ็กต์

2. แก้ไขเหตุการณ์ postbuild ของโครงการ Web API ของคุณเพื่อคัดลอกไฟล์ XML นี้ไปยังApp_Dataโฟลเดอร์ของคุณ:

   copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"

   ที่ไหนควรจะเปลี่ยนชื่อเพื่อสิ่งที่ชื่อโครงการของคุณเป็นบวกSubproject.xml.xml

3. ถัดไปเปิดAreas\HelpPage\App_Start\HelpPageConfigและค้นหาบรรทัดต่อไปนี้:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

   นี่คือบรรทัดที่คุณไม่ได้ใส่ความคิดเห็นในตอนแรกเพื่อเปิดใช้งานเอกสารวิธีใช้ XML ในตอนแรก แทนที่บรรทัดนั้นด้วย:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data")));

   ขั้นตอนนี้ทำให้แน่ใจว่าXmlDocumentationProviderถูกส่งผ่านไดเร็กทอรีที่มีไฟล์ XML ของคุณแทนที่จะเป็นไฟล์ XML เฉพาะสำหรับโปรเจ็กต์ของคุณ

4. สุดท้ายแก้ไขAreas\HelpPage\XmlDocumentationProviderด้วยวิธีต่อไปนี้:

   ก. แทนที่_documentNavigatorฟิลด์ด้วย:

   private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();

   ข. แทนที่ตัวสร้างด้วย:

   public XmlDocumentationProvider(string appDataPath)
   {
       if (appDataPath == null)
       {
           throw new ArgumentNullException("appDataPath");
       }
   
       var files = new[] { "XmlDocument.xml", "Subproject.xml" };
       foreach (var file in files)
       {
           XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
           _documentNavigators.Add(xpath.CreateNavigator());
       }
   }

   ค. เพิ่มวิธีการต่อไปนี้ด้านล่างตัวสร้าง:

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }

   ง. และสุดท้ายแก้ไขข้อผิดพลาดของคอมไพเลอร์ทั้งหมด (ควรมีสามข้อ) ส่งผลให้มีการอ้างอิง_documentNavigator.SelectSingleNodeและลบ_documentNavigator.ส่วนออกเพื่อให้เรียกใช้SelectSingleNodeวิธีการใหม่ที่เรากำหนดไว้ข้างต้น

ขั้นตอนสุดท้ายนี้คือสิ่งที่ปรับเปลี่ยนผู้ให้บริการเอกสารเพื่อรองรับการค้นหาเอกสาร XML หลายชุดสำหรับข้อความช่วยเหลือแทนที่จะเป็นเพียงโครงการหลัก

ตอนนี้เมื่อคุณตรวจสอบเอกสารวิธีใช้ของคุณจะมีเอกสาร XML จากประเภทในโครงการที่เกี่ยวข้องของคุณ

ฉันเจอสิ่งนี้เช่นกัน แต่ฉันไม่ต้องการแก้ไขหรือทำซ้ำรหัสที่สร้างขึ้นเพื่อหลีกเลี่ยงปัญหาในภายหลัง

จากคำตอบอื่น ๆ นี่คือผู้ให้บริการเอกสารในตัวสำหรับแหล่ง XML หลายแหล่ง เพียงวางสิ่งนี้ลงในโครงการของคุณ:

/// <summary>A custom <see cref="IDocumentationProvider"/> that reads the API documentation from a collection of XML documentation files.</summary>
public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
    /*********
    ** Properties
    *********/
    /// <summary>The internal documentation providers for specific files.</summary>
    private readonly XmlDocumentationProvider[] Providers;


    /*********
    ** Public methods
    *********/
    /// <summary>Construct an instance.</summary>
    /// <param name="paths">The physical paths to the XML documents.</param>
    public MultiXmlDocumentationProvider(params string[] paths)
    {
        this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(MemberInfo subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(Type subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpControllerDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpParameterDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetResponseDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetResponseDocumentation(subject));
    }


    /*********
    ** Private methods
    *********/
    /// <summary>Get the first valid result from the collection of XML documentation providers.</summary>
    /// <param name="expr">The method to invoke.</param>
    private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)
    {
        return this.Providers
            .Select(expr)
            .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
    }
}

... และเปิดใช้งานในของคุณHelpPageConfigด้วยเส้นทางไปยังเอกสาร XML ที่คุณต้องการ:

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Api.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.Models.xml")));

อีกวิธีหนึ่งที่ง่ายกว่าคือการรวมไฟล์ xml ตัวอย่างรหัสในการตอบกลับด้านล่างของฉัน:

ความคิดเห็น XML ของหน้าวิธีใช้ Web Api จากไฟล์มากกว่า 1 ไฟล์

ที่นี่ฉันให้ลิงค์คำตอบซึ่งสามารถช่วยคุณได้ คุณสามารถใช้ไฟล์ XML หลายไฟล์สำหรับเอกสารประกอบได้อย่างง่ายดาย

ความคิดเห็น XML ของหน้าวิธีใช้ Web Api จากไฟล์มากกว่า 1 ไฟล์

วิธีที่ง่ายที่สุดในการแก้ไขปัญหานี้คือการสร้างโฟลเดอร์ App_Code บนเซิร์ฟเวอร์ที่คุณปรับใช้ จากนั้นคัดลอก XmlDocument.xml ที่คุณมีในโฟลเดอร์ bin ของคุณลงในโฟลเดอร์ App_Code