記錄下 WebApi 自動(dòng)生成接口文檔實(shí)現(xiàn)方法，Swagger 或者 HelpPage 都能很好實(shí)現(xiàn) 。這里使用HelpPage實(shí)現(xiàn)。

解決方案的結(jié)構(gòu)

解決方案有3個(gè)項(xiàng)目，主要用于分層：
1.webapi，引用service和model
2.service，引用model
3.model

HelPage 配置步驟：

1. 添加HelpPage

在webapi 中 nuget引入 Microsoft.AspNet.WebApi.HelpPage 包，正常情況下會(huì)自動(dòng)添加一個(gè)HelpPage的Area，如下圖：

效果圖

到此，已經(jīng)實(shí)現(xiàn)基本功能，能夠通過(guò)xxxx/help訪問(wèn)接口文檔了。

2. 為HepPage啟用測(cè)試功能

nuget引入 Web API Test Client。若API頁(yè)面右下角沒(méi)有出現(xiàn)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文檔顯示注釋。

默認(rèn)情況下 HelpPage 僅顯示Controller中的注釋，無(wú)法顯示其他項(xiàng)目的注釋，這是因?yàn)镠elpPage使用了項(xiàng)目的XML文檔文件，而WebApi中沒(méi)有Model和Service的XML文件，那么就為Model和Service添加X(jué)ml文檔文件。

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

設(shè)置生成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.效果

實(shí)現(xiàn)效果