路由参数的 XML 注释答案

【问题标题】：XML Comments for route parameters路由参数的 XML 注释
【发布时间】：2018-08-26 17:18:26
【问题描述】：

我正在实施一个 Web API 项目，该项目将使用标准 HelpPages 区域来获取文档。我在我的项目中使用属性路由并实现了 ApiVersioning。我已经记录了我的大部分方法和模型，但是我试图弄清楚如何记录 API 版本路由参数。这是我的控制器的示例：

/// <summary>
/// Controller for the License api.
/// </summary>
[ApiVersion("1.0")]
[RoutePrefix("api/v{version:apiVersion}/license")]
public class LicenseController : ApiController
{
    #region Software License Methods

    /// <summary>
    /// Creates a new Software License.
    /// </summary>
    /// <param name="value">The parameters for the license.</param>
    /// <returns>The newly created Activation and Emergency Ids.</returns>        
    [Route("software")]
    [HttpPost]
    public LicenseCreateResponse CreateSoftwareLicense([FromBody] CreateSoftwareLicenseRequest value)
    {
       // License creation code
    }

配置 HelpArea 并运行项目后，我得到以下帮助信息：

版本参数有一个描述，但是我不知道如何记录它。就方法而言，它不是路线的一部分，因此尝试<param name="version">... 是徒劳的。

感谢您的帮助！

【问题讨论】：

标签： c# asp.net-mvc asp.net-web-api asp.net-web-api2 api-versioning

【解决方案1】：

此解决方案可能有效，但没必要那么困难。出于好奇，您是否使用官方的 API Explorer 包进行 API 版本控制？看起来不会。它提供的 IApiExplorer 实现为您记录了 API 版本参数，包括说明。

如果您想更改开箱即用提供的默认描述文本，您可以在 API Explorer 选项中轻松进行，如下所示：

configuration.AddVersionedApiExplorer(
    options => options.DefaultApiVersionParameterDescription = "The version" )

Help Pages 似乎已经过时，取而代之的是 Swagger/Swashbuckle，但 API 版本控制 API 浏览器应该与它无缝协作。如果有差距或其他痛点，我肯定有兴趣了解它们。

【讨论】：

【解决方案2】：

操作帮助页面上的 URI 参数部分用于描述从 URI 查询字符串绑定的操作参数（例如 ...?SomeParam=SomeValue）。在您的情况下，version 只是与操作参数无关的 URI 路径的一部分。因此，在 URI 参数部分对其进行描述可能会造成混淆。这就是为什么我建议将其从本节中删除并（如果需要）将version 模板的描述放到帮助页面的其他部分中。

要实现这一点，您应该：

从 URI 参数列表中删除 version。这一步并不简单，因为来自路由模板的version 被ApiExplorer 识别为操作参数。抑制它需要修改生成的代码来填充 API 帮助页面 (HelpPageApiModel) 的模型。此代码位于HelpPageConfigurationExtensions.GenerateUriParameters() 方法中。找到以下几行：

Debug.Assert(parameterDescriptor == null);
// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

并为version参数添加条件：

Debug.Assert(parameterDescriptor == null);

if (apiParameter.Documentation == null && String.Equals(apiParameter.Name, "version", StringComparison.InvariantCulture))
{
    continue;
}

// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

现在您将获得以下帮助页面：

为版本 URI 模板添加特定部分：

打开查看文件Areas\HelpPage\Views\Help\DisplayTemplates\HelpPageApiModel.cshtml 并添加您想要的版本部分。例如：
```
...

<h2>Request Information</h2>

<h3>Version info</h3>
Put some info about version here.

<h3>URI Parameters</h3>
@Html.DisplayFor(m => m.UriParameters, "Parameters")

...
```
这样的观点会给你：

如果您想在 URI 参数部分查看版本说明，您可以返回 HelpPageConfigurationExtensions.GenerateUriParameters() 方法并将上面的代码替换为以下代码：

Debug.Assert(parameterDescriptor == null);

if (apiParameter.Documentation == null && String.Equals(apiParameter.Name, "version", StringComparison.InvariantCulture))
{
    apiParameter.Documentation = "Put description for version parameter here.";
}

// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

这会给你：

嗯，这些方法并不完美（我不喜欢修改生成的HelpPageConfigurationExtensions）。但似乎没有其他方法可以抑制或填充 version 参数的描述。

【讨论】：