如何为Microsoft.AspNet.WebApi.HelpPage添加JSON示例至API文档？

我之前也碰到过一模一样的问题，帮你整理几个靠谱的解决办法，一步步来就能搞定：

第一步：先确认XML注释的基础配置是否正确 #

首先得确保你的XML注释已经被HelpPage正确识别，这是后续添加示例的前提：

• 右键你的Web API项目 → 属性 → 生成，勾选「XML文档文件」，把路径设为项目目录下的App_Data/XmlDocument.xml（路径可以自定义，只要后续配置对应上就行）。
• 打开HelpPageConfig.cs，添加以下代码启用XML注释解析：

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

方法一：直接在XML注释里写JSON示例（最简单） #

用<example>标签包裹你的请求/响应示例，配合<code>标签格式化代码，HelpPage会自动识别并展示在Sample区域：

/// <summary>
/// 创建新用户接口
/// </summary>
/// <param name="user">用户信息DTO</param>
/// <returns>创建成功后的用户详情</returns>
/// <example>
/// 请求示例：
/// <code>
/// POST /api/Users
/// Content-Type: application/json
/// {
///   "username": "johndoe",
///   "email": "john@example.com",
///   "age": 30,
///   "isActive": true
/// }
/// </code>
/// 响应示例：
/// <code>
/// HTTP/1.1 201 Created
/// Content-Type: application/json
/// {
///   "id": 1001,
///   "username": "johndoe",
///   "email": "john@example.com",
///   "age": 30,
///   "isActive": true,
///   "createTime": "2024-05-20T14:30:00Z"
/// }
/// </code>
/// </example>
public IHttpActionResult PostUser(UserDto user)
{
    // 业务逻辑实现
}

重新生成项目后刷新HelpPage，就能看到Sample区域显示你写的JSON示例了。

方法二：自定义示例提供器（自动生成实体类示例） #

如果你的接口很多，不想手动写每个示例，可以自定义示例提供器，让HelpPage自动基于实体类生成JSON示例：

1. 创建一个自定义示例提供器类，实现ISampleRequestProvider或ISampleResponseProvider：

public class CustomSampleProvider : ISampleRequestProvider
{
    public object GetSample(Type type, MediaTypeHeaderValue mediaType)
    {
        // 根据不同的实体类型返回对应的示例对象
        if (type == typeof(UserDto))
        {
            return new UserDto
            {
                Username = "johndoe",
                Email = "john@example.com",
                Age = 30,
                IsActive = true
            };
        }
        // 其他类型可以调用默认提供器生成示例
        var defaultProvider = new DefaultSampleRequestProvider();
        return defaultProvider.GetSample(type, mediaType);
    }
}

2. 在HelpPageConfig.cs里注册这个提供器：

config.SetSampleRequestProvider(new CustomSampleProvider());

这样HelpPage会自动把你返回的实体对象序列化成JSON，作为对应接口的请求/响应示例。

额外注意事项 #

• 如果你的接口返回IHttpActionResult，可以在XML注释里用<response>标签指定返回的具体类型，比如：/// <response code="200">返回类型为<UserDto>的用户详情</response>，帮助HelpPage正确识别示例类型。
• 如果自定义过HelpPage的视图文件（比如HelpPageApiModel.cshtml），要确保视图代码里包含了对<example>注释内容的渲染逻辑，默认视图是已经处理好的，除非你修改过。

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