ASP.NET WebAPI 自动生成帮助文档

当您创建一个Web API,建立了一个帮助页面非常有用。可以手动创建的所有文件,但最好是能够自动生成。

为了使这项工作更容易,ASP.NET Web API提供了自动生成帮助页面的模板,如下图

如何创建Help Page?

1、用VS2013创建的Web API 2项目会默认带有Microsoft ASP.NET Web API Help Page的包。如果没有,就需要手动去NuGet上安装。

 

2、 如果安装了这个包,创建新的Web API 项目后,Web API项目目录里会多一个Area,里面有个HelpPage文件夹,这里面放的都是HelpPage生成器的代码、页面模版和配置文件。

当你运行应用程序时,主页上包含一个链接到API帮助页面。

3、 “Description”字段的内容,是需要去配置的,Description的内容所使用的其实是代码里方法的注释,即/// <summary>形式的注释。这些东西是可以生成XML的,许多文档生成器都要使用这份XML作为metadata的来源。

在我们的网站里,这样的metadata信息通常应该放在App_Data文件夹里,而不是默认的bin目录里。所以我们要对Web API的项目属性做一些更改。

打开项目属性,在Build页面里,勾选XML documentation file,并把他放到App_Data下面:

取消Register方法中第一段代码的注释,并且把XML文件的路径改成刚才在刚才在项目属性页里设置的路径。

    config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/PatientView.Service.WebAPI.xml")));

现在,如果你在API方法上添加/// <summary>的注释,就会被生成在网页上。

原文地址:https://www.cnblogs.com/luke-lu/p/5455501.html