關於ASP.NET Web Api的HelpPage文檔註釋問題

時間 2019-12-08

標籤關於 asp.net asp web api helppage 文檔註釋問題欄目 ASP 简体版

原文原文鏈接

關於ASP.NET Web Api的HelpPage文檔註釋問題

之前我用微軟的HelpPage來自動生成的webAPI幫助文檔。在使用了一段時間後發現只能顯示Controller上面寫的註釋文檔內容。之前總覺得是微軟這個類庫的bug。後來才明白了是因爲個人設置不當。html

微軟的HelpPage類庫

controller上的註釋

AlarmRecodrdDto文檔

咱們能夠很清楚的看到，返回的`AlarmRecodrdDto`並無註釋文檔啊！但是我已經在類庫的中寫過了該代碼的註釋的。爲毛就沒有呢？？？

其實啊，咱們的註釋文檔是自動生成xml文件，再由HelpPage來讀取該xml中的註釋信息，最後展現在頁面上。那些沒有註釋的文檔是因爲咱們的代碼註釋沒有生成對應的註釋xml文件，因此就無法讀取啦！！！

明白問題出在哪裏了就能夠動手解決問題了！！！web

1. 設置指定類庫中要生成的註釋xml路徑

GTCASP.Services.xml

GTCASP.Models.xml

XMLDocument.xml

2. 添加一個能夠讀取xml文件信息的類

using System;
using System.Linq;
using System.Reflection;
using System.Web.Http.Controllers;
using System.Web.Http.Description;
using GTCASP.Website.Areas.HelpPage.ModelDescriptions;

namespace GTCASP.Website.Areas.HelpPage.Models
{
    /// <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.GetDocumentation(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));
        }
    }
}