创建WebAPI文档的3个简单步骤(示例)

・2 分钟阅读

默认情况下,Microsoft.AspNet.WebApi.HelpPage创建的API帮助页不包含任何文档。 我们会看到所有的ApiController动作都列在No documentation available.

Picture

要启用文档,我们只需要遵循三个简单步骤。

步骤1-在控制器级别上

为了测试目的,创建了一个新的ApiController,名为DocumentationsController


public class DocumentationsController : ApiController
{
 // GET api/documentation
 public IEnumerable<string> Get()
 {
 return new string[] {"value1","value2" };
 }
....

在控制器操作前点击///以获取文档。


// GET api/documentation
/// <summary>
/// This is how we create a documentation
/// </summary>
/// <returns></returns>
public IEnumerable<string> Get()
....

有关可以记录的内容的详细信息,可以按"<"来出现IntelliSense,或转到MSDN页面

步骤2-生成属性

调出项目属性页,并且设置文档的xml输出,在本例中,文档文件将是App_DataDocumentation.XML

Picture

步骤3- HelpPage配置

若要将HelpPageConfig设置为使用我们的文档xml文件,请转到~AreasHelpPageHelpPageConfig.cs

默认情况下,config.SetDocumentationProvider语句被注释掉,使用该语句,并将DocumentationProvider的位置指向我们的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/Documentation.xml")));

现在我们可以做一个构建和刷新api documenation页面:

Picture

当然,也创建了文档文件:

图片

注意文档正确显示,很简单吧?!

讨论
Jiaoyang75 profile image