Asp.net Web Api开发（第四篇）Help Page配置和扩展

为了方面APP开发人员，服务端的接口都应当提供详尽的API说明。但每次有修改，既要维护代码，又要维护文档，一旦开发进度紧张，很容易导致代码与文档不一致。

Web API有一个Help Page插件，可以很方便的根据代码及注释自动生成相关API说明页面。

Help Page安装步骤及扩展(以VS2015为例)：

右键点击WebAPI项目的引用，选择"管理NuGet程序包"

在搜索框中输入 helppage进行搜索，结果如下图：

然后在右侧边栏点击安装按钮即可进行插件安装了。

安装完成后，你会发现项目下多了不少文件：

接下来，我们对Areas/HelpPage/App_Start/HelpPageConfig.cs进行改造。

改造前，我们需要先了解下HelpPageConfig.cs，其中的Register方法是用于注册Help Page页面需要展示的API的文档的。默认情况下，该方法只支持单个文档导入，所以我们需要扩展下。

我们创建一个可多文件注册的类：

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

namespace WebApplication2.Areas.HelpPage.App_Start
{
    public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
    {
        private readonly XmlDocumentationProvider[] Providers;
        public MultiXmlDocumentationProvider(params string[] paths)
        {
            this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
        }

        public string GetDocumentation(MemberInfo subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        public string GetDocumentation(Type subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        public string GetDocumentation(HttpControllerDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        public string GetDocumentation(HttpActionDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        public string GetDocumentation(HttpParameterDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        public string GetResponseDocumentation(HttpActionDescriptor subject)
        {
            return this.GetFirstMatch(p => p.GetDocumentation(subject));
        }

        private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)
        {
            return this.Providers
                .Select(expr)
                .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
        }
    }
}

然后重写HelpPageConfig.cs文件中的代码如下：

using System.Diagnostics.CodeAnalysis;
using System.Web;
using System.Web.Http;
using WebApplication2.Areas.HelpPage.App_Start;

namespace WebApplication2.Areas.HelpPage
{
    public static class HelpPageConfig
    {
        [SuppressMessage("Microsoft.Globalization", "CA1303:Do not pass literals as localized parameters",
            MessageId = "WebApplication2.Areas.HelpPage.TextSample.#ctor(System.String)",
            Justification = "End users may choose to merge this string with existing localized resources.")]
        [SuppressMessage("Microsoft.Naming", "CA2204:Literals should be spelled correctly",
            MessageId = "bsonspec",
            Justification = "Part of a URI.")]
        public static void Register(HttpConfiguration config)
        {
            config.SetDocumentationProvider(new MultiXmlDocumentationProvider(
                HttpContext.Current.Server.MapPath("~/bin/WebApplication2.XML")));
        }
    }
}

这里要注意下WebApplication2.XML，这个文件是需要我们对相关项目属性进行设置下的，让其生成相关xml文件。

然后我们来创建一个Controller用于测试。

using System.Web.Http;

namespace WebApplication2.Controllers
{
    /// <summary>
    /// 测试响应对象
    /// </summary>
    public struct TestResponse {
        /// <summary>
        /// 姓名
        /// </summary>
       public string Name;
        /// <summary>
        /// 年龄
        /// </summary>
        public int Age;
    }

    /// <summary>
    /// 测试
    /// </summary>
    public class TestController : ApiController
    {
        /// <summary>
        /// 测试接口
        /// </summary>
        /// <returns></returns>
        [HttpPost]
        [Route("api/300/1000")]
        public TestResponse JustTest()
        {
            return new TestResponse() { Name = "测试员", Age = 26 };
        }
    }
}

因为创建的是Web API项目，所以这里还要修改下Global.asax，注册Area。

using System.Web.Http;
using System.Web.Mvc;

namespace WebApplication2
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            AreaRegistration.RegisterAllAreas();
            GlobalConfiguration.Configure(WebApiConfig.Register);
        }
    }
}

接下来，编译运行调试起来，效果如下图。

Asp.net Web Api开发（第四篇）Help Page配置和扩展

猜你喜欢