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.效果