WebApi中帮助页Description的中文显示

转自:http://edi.wang/post/2013/10/28/auto-generate-help-document-aspnet-webapi

我选择Web API的一个重要原因就是因为可以自动生成文档,省去了开发人猿不少宝贵的时间。以前在用Web API第一代的时候,自动生成帮助文档的功能默认是不完整的,现在到了Web API 2,这个功能已经通过NuGet包的形式很好的整合到了一起。我们来看一下吧!

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

WebApi中帮助页Description的中文显示

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

WebApi中帮助页Description的中文显示

在不做任何更改的情况下,你的WebAPI项目现在就已经具有基本的生成文档的功能了。

浏览/Help,即Areas.HelpPage.Controllers.HelpController的Index() Action,就能看到自动生成的API文档:

WebApi中帮助页Description的中文显示

你们可能注意到,我的表格里“Description”字段是有内容的,而你们自己的是木有的。这个其实是需要额外去配置的。

这个Description的内容所使用的其实是代码里方法的注释,即/// <summary>形式的注释。如果你有撸过类库的经验,你会知道这些东西是可以生成XML的,许多文档生成器都要使用这份XML作为metadata的来源。

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

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

WebApi中帮助页Description的中文显示

然后打开Areas\HelpPage\App_Start下的HelpPageConfig.cs

WebApi中帮助页Description的中文显示

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

public static void Register(HttpConfiguration config)
{
// Uncomment the following to use the documentation from XML documentation file.
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/PatientView.Service.WebAPI.xml"))); ...
}

现在,如果你在API方法上写三斜杠的注释,就会被生成在网页上。

上一篇:转MYSQL学习(三) 函数


下一篇:iOS 并行编程:NSOperation Queues