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参数”部分中查看版本说明，则可以返回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版本参数的文档，包括描述。

如果您想要更改开箱即用的默认描述文本，您可以在API Explorer选项中轻松完成此操作：

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

帮助页面似乎已经过时了，转而支持Swagger / Swashbuckle，但API Versioning API资源管理器应该与它无缝协作。如果有空隙或其他痛点，我肯定有兴趣听到它们。

路由参数的XML注释

2 个答案: