码迷,mamicode.com
首页 > Windows程序 > 详细

Web Api HelpPage

时间:2018-05-24 11:47:52      阅读:237      评论:0      收藏:0      [点我收藏+]

标签:UNC   multi   SM   ext   插件安装   names   响应   维护   isnull   

为了方面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);  
        }  
    }  
}  

技术分享图片

 

原文地址: https://blog.csdn.net/sqqyq/article/details/52708613#

Web Api HelpPage

标签:UNC   multi   SM   ext   插件安装   names   响应   维护   isnull   

原文地址:https://www.cnblogs.com/lenmom/p/9081363.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!