Web API项目中如何为API版本路由参数编写HelpPages文档？

我之前做类似项目的时候也碰到过这个问题，默认的HelpPages确实不会自动识别apiVersion这个路由参数的文档，下面给你两种靠谱的解决方式：

方式一：使用官方ApiVersioning HelpPage扩展包（推荐） #

这是最省心的方法，微软专门提供了适配HelpPages的ApiVersioning扩展，步骤如下：

1. 先安装NuGet包：

Install-Package Microsoft.AspNet.WebApi.Versioning.HelpPage

2. 在App_Start/HelpPageConfig.cs里启用API版本的HelpPages支持，替换原有的文档提供器配置：

using Microsoft.Web.Http.Versioning;

public static class HelpPageConfig
{
    public static void Register(HttpConfiguration config)
    {
        // 其他HelpPages配置...

        // 启用API版本的HelpPages支持
        var xmlPath = HttpContext.Current.Server.MapPath("~/App_Data/你的API文档.xml");
        config.SetDocumentationProvider(new XmlDocumentationProvider(xmlPath));
        config.EnableApiVersioningHelpPage();
    }
}

这样配置后，HelpPages会自动识别路由中的version:apiVersion参数，并且展示API版本相关的说明，包括支持的版本号等信息。

方式二：自定义文档提供器（无需额外安装包） #

如果不想加新的NuGet包，可以通过自定义XmlDocumentationProvider来手动添加参数说明：

1. 创建自定义的文档提供器类：

using System.Web.Http.Controllers;
using System.Web.Http.Description;

public class CustomApiDocProvider : XmlDocumentationProvider
{
    public CustomApiDocProvider(string documentPath) : base(documentPath)
    {
    }

    public override string GetParameterDocumentation(HttpParameterDescriptor parameterDescriptor)
    {
        // 匹配路由中的version参数
        if (parameterDescriptor.ParameterName == "version" 
            && parameterDescriptor.RouteInfo != null 
            && parameterDescriptor.RouteInfo.Constraint is ApiVersionRouteConstraint)
        {
            return "指定调用的API版本号，例如：1.0、2.0";
        }
        // 其他参数用默认逻辑
        return base.GetParameterDocumentation(parameterDescriptor);
    }
}

2. 在HelpPageConfig.cs里替换默认的文档提供器：

public static void Register(HttpConfiguration config)
{
    // 其他HelpPages配置...

    var xmlPath = HttpContext.Current.Server.MapPath("~/App_Data/你的API文档.xml");
    config.SetDocumentationProvider(new CustomApiDocProvider(xmlPath));
}

额外小技巧：给控制器添加版本相关的备注 #

你还可以在控制器的注释里补充版本路由的说明，让开发者更清楚：

/// <summary>
/// License API控制器。
/// </summary>
/// <remarks>
/// 路由说明：
/// - version: 必填，API版本标识，当前支持1.0版本
/// </remarks>
[ApiVersion("1.0")]
[RoutePrefix("api/v{version:apiVersion}/license")]
public class LicenseController : ApiController
{
    // 你的API方法...
}

这个备注会在HelpPages的控制器详情页面显示，和路由参数说明形成互补。

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