WebAPI HelpPage帮助页

Posted 贰拾

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了WebAPI HelpPage帮助页相关的知识,希望对你有一定的参考价值。

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列下面是说明。

 

 

 

 

 

 

 

 

 

 

 

以上是关于WebAPI HelpPage帮助页的主要内容,如果未能解决你的问题,请参考以下文章

WebAPI HelpPage支持area

转如何在Web项目中给没有添加API核心组件添加APIController的帮助页HelpPage

如何在Web项目中给没有添加API核心组件添加APIController的帮助页HelpPage

Web Api HelpPage

WebAPI使用多个xml文件生成帮助文档

visual studio 2015中的webapi生成helpPage,页面不显示方法说明问题解决