Làm cách nào để Tài liệu Xml cho Web Api có thể bao gồm tài liệu từ bên ngoài dự án chính?

Các tài liệu cho phép tích hợp vào các dự án XMLdoc Api web của bạn dường như chỉ những tình huống xử lý mà tất cả các loại API của bạn là một phần của dự án WebAPI của bạn. Đặc biệt, nó thảo luận về cách định tuyến lại tài liệu XML đến App_Data/XmlDocument.xmlvà bỏ ghi chú một dòng trong cấu hình của bạn sẽ sử dụng tệp đó. Điều này mặc nhiên chỉ cho phép một tệp tài liệu của dự án.

Tuy nhiên, trong thiết lập của mình, tôi đã xác định các loại yêu cầu và phản hồi trong dự án "Mô hình" chung. Điều này có nghĩa là nếu tôi có một điểm cuối được xác định như:

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

Nơi OpenIdLoginRequestđược xác định trong một dự án C # riêng biệt như vậy:

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

    ...
}

Mặc dù doccomments XML, các thuộc tính của requesttham số không chứa tài liệu khi bạn xem trang trợ giúp dành riêng cho điểm cuối (tức là http://localhost/Help/Api/POST-auth-openid-login).

Làm cách nào để tôi có thể thực hiện nó để các loại trong dự án con có tài liệu XML được hiển thị trong tài liệu XML của Web API?

Không có cách tích hợp nào để đạt được điều này. Tuy nhiên, nó chỉ yêu cầu một vài bước:

1. Bật tài liệu XML cho dự án con của bạn (từ các thuộc tính / bản dựng của dự án) giống như bạn có cho dự án API Web của mình. Ngoại trừ lần này, hãy định tuyến nó trực tiếp để XmlDocument.xmlnó được tạo trong thư mục gốc của dự án của bạn.

2. Sửa đổi sự kiện tạo sau của dự án API Web của bạn để sao chép tệp XML này vào App_Datathư mục của bạn :

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

   Nơi Subproject.xmlnên được đổi tên thành bất cứ điều gì cộng với tên dự án của bạn .xml.

3. Tiếp theo, mở Areas\HelpPage\App_Start\HelpPageConfigvà tìm dòng sau:

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

   Đây là dòng ban đầu bạn đã bỏ ghi chú để kích hoạt tài liệu trợ giúp XML ngay từ đầu. Thay thế dòng đó bằng:

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

   Bước này đảm bảo rằng XmlDocumentationProviderthư mục chứa các tệp XML của bạn được chuyển qua, thay vì tệp XML cụ thể cho dự án của bạn.

4. Cuối cùng, sửa đổi Areas\HelpPage\XmlDocumentationProvider theo những cách sau:

   a. Thay thế _documentNavigatortrường bằng:

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

   b. Thay thế hàm tạo bằng:

   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());
       }
   }

   c. Thêm phương thức sau vào bên dưới hàm tạo:

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

   d. Và cuối cùng, hãy sửa tất cả các lỗi trình biên dịch (nên có ba) dẫn đến các tham chiếu đến _documentNavigator.SelectSingleNodevà loại bỏ _documentNavigator.phần để bây giờ nó gọi SelectSingleNodephương thức mới mà chúng tôi đã xác định ở trên.

Bước cuối cùng này là những gì sửa đổi trình cung cấp tài liệu để hỗ trợ tìm kiếm trong nhiều tài liệu XML cho văn bản trợ giúp thay vì chỉ của dự án chính.

Bây giờ khi bạn kiểm tra tài liệu Trợ giúp của mình, nó sẽ bao gồm tài liệu XML từ các loại trong dự án liên quan của bạn.

Tôi cũng gặp phải vấn đề này, nhưng tôi không muốn chỉnh sửa hoặc sao chép bất kỳ mã nào đã tạo để tránh sự cố sau này.

Dựa trên các câu trả lời khác, đây là một nhà cung cấp tài liệu độc lập cho nhiều nguồn XML. Chỉ cần thả cái này vào dự án của bạn:

/// <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));
    }
}

... và kích hoạt nó trong của bạn HelpPageConfigvới các đường dẫn đến các tài liệu XML mà bạn muốn:

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

Một cách đơn giản hơn để thực hiện việc này là hợp nhất các tệp xml. Mã ví dụ trong câu trả lời dưới đây của tôi:

Trang Trợ giúp Web Api Nhận xét XML từ nhiều hơn 1 tệp

ở đây tôi cung cấp một liên kết câu trả lời với nó, có thể giúp bạn. Bạn có thể dễ dàng sử dụng nhiều tệp XML để làm tài liệu.

Trang Trợ giúp Web Api Nhận xét XML từ nhiều hơn 1 tệp

Cách dễ nhất để khắc phục sự cố này là tạo thư mục App_Code trên máy chủ mà bạn đã triển khai. Sau đó sao chép cục bộ XmlDocument.xml bạn có trong thư mục bin của mình vào thư mục App_Code