XML 路由参数评论

Question

我正在实施一个 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">... 是徒劳的。

感谢您的帮助！

Answer 1

操作帮助页面上的 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 参数部分看到版本描述，你可以 return 到 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 参数的描述。

Answer 2

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

如果您想更改提供的默认描述文本 out-of-the-box，您可以在 API 资源管理器选项中轻松地这样做：

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

帮助页面 似乎已经过时，取而代之的是 Swagger/Swashbuckle，但是 API 版本控制 API 浏览器应该可以与它。如果存在差距或其他痛点，我肯定有兴趣了解它们。

XML 路由参数评论

XML Comments for route parameters

c#

asp.net-mvc

asp.net-web-api

asp.net-web-api2

api-versioning