ASP.NET Web API根据代码注释生成Help文档

Posted 2020-07-26 Niko12230

使用Visual Studio新建一个ASP.NET Web API项目，直接运行，查看Help文档可以看到如下的API帮助说明

 

如何在Description中显示描述。

1. 打开Controllers=>ValuesController，为每个API增加注释(Summary)

public class ValuesController : ApiController
{
    /// <summary>
    /// GET api/values
    /// </summary>
    /// <returns></returns>
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    /// <summary>
    /// GET api/values/5
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    public string Get(int id)
    {
        return "value";
    }

    /// <summary>
    /// POST api/values
    /// </summary>
    /// <param name="value"></param>
    public void Post([FromBody]string value)
    {
    }

    /// <summary>
    /// api/values/5
    /// </summary>
    /// <param name="id"></param>
    /// <param name="value"></param>
    public void Put(int id, [FromBody]string value)
    {
    }

    /// <summary>
    /// api/values/5
    /// </summary>
    /// <param name="id"></param>
    public void Delete(int id)
    {
    }
}

2. 打开项目的属性页=>Build，钩选Output=>XML documentation file:并输入存放项目注释文档的路径。

 

3. 修改如下代码

Areas=>HelpPage=>App_Start=>HelpPageConfig.cs，取消该行注释

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

注意路径必须和上面的自己配置的路径一致。

4. 重新生成项目，在App_Data下会生成XmlDocument.xml文件

5. 再次查看Help页，会发现API的注释已经增加。