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

目前在做的项目里要用到RESTful Service，一开始是用WCF WebHttpBinding撸的，但我知道WebAPI才是最适合的，正好现在VS2013 RTM了，Web API 2也跟着ASP.NET MVC5一起发布了，于是今天就把Service用Web API 2重写了一下。

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

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

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

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

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

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

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

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

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

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

取消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方法上写三斜杠的注释，就会被生成在网页上。

/// <summary>
/// 病区列表
/// </summary>
/// <returns></returns>
[Route("GetLocationUnits")]
public Response<List<LocationUnitModel>> GetLocationUnits()
{
    return TryResponse(() => _operatorBll.GetLocationUnits(),
        method: "GetLocationUnits");
}

Microsoft MVP for Azure