如何在Web API帮助页面展示请求与响应体的参数

问题说明 #

我希望在Web API的帮助页面中，将请求和响应体以参数列表形式展示，而非原始JSON/XML数据。参考了相关方案后仍未成功，当前页面依然显示原始数据格式。

当前效果截图：

当前代码示例 #

/// <summary>
/// 从服务器获取重要数据。
/// </summary>
/// <param name="reqData">测试模型</param>
[HttpPost]
public AccountService.GetAccountList_ResponseData GetAccountList([FromBody] AccountService.GetAccountList_ReqestData reqData)
{
}

// 模型定义
public class GetAccountList_ReqestData 
{
    /// <summary>
    /// 开始日期
    /// </summary>
    /// <param name="StartDate">参数描述</param>
    public string StartDate { get; set; }
}

// 已启用XML文档提供器
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.xml")));

解决步骤 #

1. 修正模型注释格式 #

Web API的XML文档解析对模型属性的注释有特定要求，不要用<param>标签（该标签用于方法参数），直接用<summary>描述属性即可：

public class GetAccountList_ReqestData 
{
    /// <summary>
    /// 数据查询的开始日期，格式为YYYY-MM-DD
    /// </summary>
    public string StartDate { get; set; }
}

2. 确保XML文档生成正确 #

• 在项目属性的「生成」选项卡中，勾选「XML文档文件」，确保输出路径和代码中WebApi.xml的路径一致。
• 重新生成项目，确认WebApi.xml文件包含模型属性的注释内容。

3. 自定义帮助页面模板（核心步骤） #

Web API自带的帮助页面默认不会展开请求体模型为参数列表，需要修改帮助页面模板：

1. 找到项目中Areas/HelpPage/Views/Help/DisplayTemplates文件夹，编辑或新建Parameters.cshtml：

@using System.Web.Http
@using System.Web.Http.Description
@model IEnumerable<ParameterDescription>

@if (Model.Any())
{
    <table class="table table-bordered table-striped">
        <thead>
            <tr>
                <th>参数</th>
                <th>描述</th>
                <th>类型</th>
                <th>是否必填</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var parameter in Model)
            {
                <tr>
                    <td>@parameter.Name</td>
                    <td>@parameter.Documentation</td>
                    <td>@parameter.ParameterType.Name</td>
                    <td>@(parameter.IsRequired ? "是" : "否")</td>
                </tr>
                // 处理复杂类型，展开属性
                if (parameter.ParameterType.IsClass && parameter.ParameterType != typeof(string))
                {
                    var properties = parameter.ParameterType.GetProperties();
                    foreach (var prop in properties)
                    {
                        var propDoc = parameter.DocumentationProvider.GetDocumentation(prop);
                        <tr>
                            <td>&nbsp;&nbsp;└ @prop.Name</td>
                            <td>@propDoc</td>
                            <td>@prop.PropertyType.Name</td>
                            <td>@(!prop.PropertyType.IsNullableType() ? "是" : "否")</td>
                        </tr>
                    }
                }
            }
        </tbody>
    </table>
}
else
{
    <p>无参数</p>
}

2. 编辑Areas/HelpPage/Views/Help/Api.cshtml，找到展示请求体的部分，替换为调用上述模板来展示参数列表，而非原始数据。

4. 备选方案：改用Swagger（更简便） #

如果自定义模板太繁琐，推荐集成Swagger（如Swashbuckle），它默认会自动展开请求/响应模型为参数列表，且支持更丰富的文档功能：

• 安装NuGet包：Install-Package Swashbuckle.AspNetWebApi
• 在WebApiConfig.cs中配置Swagger：

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "你的API名称");
    c.IncludeXmlComments(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.xml"));
})
.EnableSwaggerUi(c =>
{
    // 可按需配置UI选项
});

内容的提问来源于stack exchange，提问作者pramod maurya