c# - 路由参数的 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 并运行项目后，我得到以下帮助信息：

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

谢谢你的帮助！

score 1 · Accepted Answer

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

为此，您应该：

version从 URI 参数列表中删除。这一步并不简单，因为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);

这会给你：

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

score 1 · Accepted Answer

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

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

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

帮助页面似乎已经过时，支持 Swagger/Swashbuckle，但 API 版本控制 API 浏览器应该与它无缝协作。如果有差距或其他痛点，我肯定有兴趣了解它们。

c# - 路由参数的 XML 注释

2 回答 2

Related

Reference