WebApi 生成接口文檔

記錄下 WebApi 自動生成接口文檔實現方法，Swagger 或者 HelpPage 都能很好實現 。這裏使用HelpPage實現。

解決方案的結構

解決方案有3個項目，主要用於分層：
1.webapi，引用service和model
2.service，引用model
3.model

HelPage 配置步驟：

1. 添加HelpPage

在webapi 中 nuget引入 Microsoft.AspNet.WebApi.HelpPage 包，正常狀況下會自動添加一個HelpPage的Area，以下圖：

到此，已經實現基本功能，可以經過xxxx/help訪問接口文檔了。

2. 爲HepPage啓用測試功能

nuget引入 Web API Test Client。若API頁面右下角沒有出現TEST API按鈕，則參照以下代碼修改Api.cshtml：

@using System.Web.Http
@using WebApi.Areas.HelpPage.Models
@model HelpPageApiModel
@section Scripts {
    @Html.DisplayForModel("TestClientDialogs")
    @Html.DisplayForModel("TestClientReferences")
}

@{
    var description = Model.ApiDescription;
    ViewBag.Title = description.HttpMethod.Method + " " + description.RelativePath;
}

<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
<div id="body" class="help-page">
    <section class="featured">
        <div class="content-wrapper">
            <p>
                @Html.ActionLink("Help Page Home", "Index")
            </p>
        </div>
    </section>
    <section class="content-wrapper main-content clear-fix">
        @Html.DisplayForModel()
    </section>
</div>

3.爲API文檔顯示註釋。

默認狀況下 HelpPage 僅顯示Controller中的註釋，沒法顯示其餘項目的註釋，這是由於HelpPage使用了項目的XML文檔文件，而WebApi中沒有Model和Service的XML文件，那麼就爲Model和Service添加Xml文檔文件。

首先，右鍵Model和Service項目，選擇屬性，在生成欄中找到輸出，勾選XML文檔文件，記住文件名

而後，在HelpPage中新增MultiXmlDocumentationProvider類，用於讀取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.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));
        }
    }

而後修改~/Area/HelpPage/App_Start/HelpPageConfig.cs的Register方法，以下：

config.SetDocumentationProvider(
                new MultiXmlDocumentationProvider(
                    HttpContext.Current.Server.MapPath("~/bin/WebApi.xml")
                    , HttpContext.Current.Server.MapPath("~/bin/Service.xml")
                    , HttpContext.Current.Server.MapPath("~/bin/Model.xml")));

所有大功告成！

4.效果