在 ASPNET Core 的路由中使用 ApiExplorerSettings GroupName

Posted 2023-04-13

【中文标题】在 ASPNET Core 的路由中使用 ApiExplorerSettings GroupName

【英文标题】：Using ApiExplorerSettings GroupName in Route in ASPNET Core

【发布时间】：2020-12-10 08:45:49

【问题描述】：

在 ASP.NET Core - Web API 项目中

在 ApiController 上使用 [ApiExplorerSettings(GroupName = "<group-name>")] 装饰 并在[Route] 属性中我想参考GroupName 属性值。

另外请注意，我在同一控制器上确实有 [ApiVersion("<some-version>")] 可以进一步分类。

这里有一些示例来解释：

示例 1：

LeadController 上的属性：[ApiVersion("1.0"), ApiExplorerSettings(GroupName = "sales"), [Route("api/groupName/vversion:apiVersion/leads"]

预期的翻译路径格式：/api/sales/v1/leads

AccountsController 上的属性：[ApiVersion("2.1"), ApiExplorerSettings(GroupName = "finance"), [Route("api/groupName/vversion:apiVersion/accounts"]

预期的翻译路径格式：/api/finance/v2.1/leads

在上面的version:apiVersion 给了我ApiVersion 值（我假设是因为该属性已将 ToString 设置为版本值）。但是当我尝试groupName 或grp:groupName 或grp:ApiExplorerSettings.GroupName 时，它们都不起作用。如何在路由属性中访问这个组名？

【参考方案1】：

你在其他地方有什么特殊设置吗，在我这边可以正常工作。

LeadController：

[ApiVersion("1.0"), ApiExplorerSettings(GroupName = "sales"),Route("api/groupName/vversion:apiVersion/leads")]
[ApiController]
public class LeadController : ControllerBase

    public string Get()
    
        return "sales group";
    

AccountsController：

[ApiVersion("2.1"), ApiExplorerSettings(GroupName = "finance"), Route("api/groupName/vversion:apiVersion/accounts")]
[ApiController]
public class AccountsController : ControllerBase

    public string Get()
    
        return "finance group";
    

结果：

【讨论】：

那是正确的 - 我没有尝试那样 - 但问题是当我在项目中配置的 Swagger UI 页面中看到相同的端点时，我仍然看到未替换的 groupName - 任何想法为什么？不过感谢您的帮助。例如。当我大摇大摆地看到/api/groupName/v1.0/leads

【参考方案2】：

ApiExplorerSettings.GroupName 仅用于 API 描述中使用的逻辑组名称。它不在路由模板中使用或评估。没有办法让它发挥作用。这就是为什么它永远不会扩展。可以使用groupName 路由参数，但它只是一个路由参数。

您是尝试控制 API Explorer 的分组还是使用路由参数并不完全清楚。 API Explorer 通常使用分组。 API 版本控制将分配或覆盖组名称，以便 API 按其版本进行分桶。可以更改此行为，但您需要 API Explorer（通过 IApiDescriptionProvider）或 OpenAPI/Swagger 文档生成器扩展来执行此操作。

【讨论】：

老实说，我不确定您所说的“它没有在路线模板中使用或评估。没有办法让它发挥作用。” - 但我能够在 ActionDescriptor - Endpoint Route details - 中找到它 - 问题是它没有像我在 Swagger JSON 中为每个组名创建单独的 OpenAPI json 那样被拾取 - 我在 mj1313 给出了相同的提示后发现- 现在我添加了我的自定义招摇逻辑来做同样的事情。现在一切都好，感谢您的帮助

正确。真高兴你做到了。我只是说ApiExplorerSettings.GroupName != groupName。实际上，您甚至不需要 groupName 以您拥有事物的方式。您可以使用 ApiExplorerSettings.GroupName 在 OpenAPI 文档中进行分组，但这与 groupName 无关。我建议摆脱 groupName 并在您的路线模板中使用 finance 和 sales 文字（根据您的示例）

同意，你一点都没错——但我有 4-5 个这样的组名来管理和指导团队正确使用它——所以他们的目标是不要拼错或遇到问题 - 我创建了固定的名字对象，这些名字对象用 groupName 映射回来，因此它们遵循模板而不是硬编码路由模板中的关键字。