问路由参数的XML注释

EN

这个解决方案可能有效，但不需要那么困难。出于好奇，您是否正在使用官方的API资源管理器包进行API版本控制？看上去不像。IApiExplorer实现它为您提供了API版本参数的文档，包括描述。

如果您想要更改默认的说明文本，可以在API Explorer选项中这样做：

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

帮助页面似乎已经过时，倾向于Swagger/Swashbuckle，但是API版本化API资源管理器应该与它无缝地工作。如果有空白或其他疼痛点，我肯定会有兴趣听到他们。

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

要做到这一点，你应该：

1. 从URI参数列表中删除version。这一步并不简单，因为来自路由模板的version被ApiExplorer识别为动作参数。要抑制它，就需要修改生成的代码，以填充API帮助页面模型(HelpPageApiModel)。此代码驻留在HelpPageConfigurationExtensions.GenerateUriParameters()方法中。可以找到以下几行： Debug.Assert(parameterDescriptor == null)；//如果parameterDescriptor为null，则这是一个未声明的路由参数，仅在源为FromUri时发生//。在请求模型中和资源参数之间忽略，但在这里将//作为一个简单字符串列出。modelGenerator.GetOrCreateModelDescription(typeof(string))；AddParameterDescription(apiModel，apiParameter，modelDescription)； 并为version参数添加条件： Debug.Assert(parameterDescriptor == null)；if (apiParameter.Documentation == null & String.Equals(apiParameter.Name，"version"，StringComparison.InvariantCulture)) {==；}/如果parameterDescriptor为null，则这是一个未声明的路由参数，仅在源为FromUri时发生/。在请求模型中和资源参数之间忽略，但在这里将//作为一个简单字符串列出。modelGenerator.GetOrCreateModelDescription(typeof(string))；AddParameterDescription(apiModel，apiParameter，modelDescription)； 现在，您将获得以下帮助页面：

​

1. 添加版本URI模板的特定部分： 打开视图文件Areas\HelpPage\Views\Help\DisplayTemplates\HelpPageApiModel.cshtml并添加所需的版本部分。例如： ..。请求信息版本信息在这里放置一些关于版本的信息。URI参数@Html.DisplayFor(m => m.UriParameters，参数). 这样的观点会让你：

​

但是，如果您想在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参数的描述。