WebAPI HelpPage帮助页

Posted 2020-11-23 贰拾

WebAPI HelpPage是个插件，根据代码的注释生成API说明页，一目了然。

下面开始安装和配置

1.添加引用

　　先选择管理NuGet程序包，搜索 Microsoft.AspNet.WebApi.HelpPage 然后当然是安装啦~~~

 

 

 

 

安装完成后我们看项目下是不是多出了一个文件夹Areas ,就是它

 

 

2.添加扩展

 

 到了这步，我们先了解下App_Start 下的 HelpPageConfig.cs  ，打开后一堆注释，一个Register方法，它用来注册HelpPage页面需要展示的API的文档的。

默认支持单文档导入，我们建立一个支持多文件注册类

using APIDemo.Areas.HelpPage.ModelDescriptions;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Reflection;
using System.Web;
using System.Web.Http.Controllers;
using System.Web.Http.Description;

namespace APIDemo.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文件中的代码，注意XML地址：

 

 namespace APIDemo.Areas.HelpPage

{

　　public static class HelpPageConfig

    {

        [SuppressMessage("Microsoft.Globalization", "CA1303:Do not pass literals as localized parameters",

            MessageId = "APIDemo.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.SetSampleForMediaType(

            //    new TextSample("Binary JSON content. See http://bsonspec.org for details."),

            //    new MediaTypeHeaderValue("application/bson"));

            config.SetDocumentationProvider(new MultiXmlDocumentationProvider(

        HttpContext.Current.Server.MapPath("~/bin/APIDemo.xml")));

　　　　｝

　　｝

｝

 

 3.XML文档文件设置

　　"~/bin/APIDemo.xml"这个文件需要我们在属性下设置的，让其生成相关xml文件

　　右击项目=》属性=》生成=》勾选XML文档文件，填写地址，把上面的地址填进去。

4.注册

　　进入到Global.asax的Application_Start方法看看有没有注册上Area

　

　protected void Application_Start()

        {

            AreaRegistration.RegisterAllAreas();

            GlobalConfiguration.Configure(WebApiConfig.Register);  

            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters); 

            RouteConfig.RegisterRoutes(RouteTable.Routes);

            BundleConfig.RegisterBundles(BundleTable.Bundles);

        }

 

 

然后就可以建立控制器测试下好了没，下面是我的控制器

 

 

 

 

 

 public class NewsController : ApiController
    {
        /// <summary>
        /// 说明写这里
        /// </summary>
        /// <returns></returns>
       public IEnumerable<News> GetAllNews()
        {
            var news = NewsRepository.GetAllNews();
            return news;
        }
    }

 

 

 

 

运行：

其实看Areas文件夹下的控制器文件夹，有一个HelpController的控制器，生成了几个 Action

 public ActionResult Index()
        {
            ViewBag.DocumentationProvider = Configuration.Services.GetDocumentationProvider();
            return View(Configuration.Services.GetApiExplorer().ApiDescriptions);
        }

        public ActionResult Api(string apiId)
        {
            if (!String.IsNullOrEmpty(apiId))
            {
                HelpPageApiModel apiModel = Configuration.GetHelpPageApiModel(apiId);
                if (apiModel != null)
                {
                    return View(apiModel);
                }
            }

            return View(ErrorViewName);
        }

        public ActionResult ResourceModel(string modelName)
        {
            if (!String.IsNullOrEmpty(modelName))
            {
                ModelDescriptionGenerator modelDescriptionGenerator = Configuration.GetModelDescriptionGenerator();
                ModelDescription modelDescription;
                if (modelDescriptionGenerator.GeneratedModels.TryGetValue(modelName, out modelDescription))
                {
                    return View(modelDescription);
                }
            }

            return View(ErrorViewName);
        }

　　

我们可以看到Index， 访问它就可以呈现下面的页面了。

 

 

 到这里就成功了，API列下有访问的地址，Description列下面是说明。