zoukankan      html  css  js  c++  java
  • Web Api HelpPage

    为了方面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#

  • 相关阅读:
    BadUSB 利用
    java 将函数作为参数传递
    odoo12 修行提升篇之 常用的高阶函数 (二)
    odoo12 修行提升篇之 异步定时任务 (一)
    odoo12 修行基础篇之 利用kanban做分析 点击跳转分析模型列表 (九)
    odoo12 修行基础篇之 kanban (八)
    odoo12 修行基础篇之 记录批处理 (七)
    odoo12 修行基础篇之 列表的筛选和分组 (六)
    odoo12 修行基础篇之 添加记录编码 (五)
    odoo12 修行基础篇之 添加工作流和操作记录 (四)
  • 原文地址:https://www.cnblogs.com/lenmom/p/9081363.html
Copyright © 2011-2022 走看看