0

我正在尝试组织我的招摇文档，但遇到了障碍。版本控制非常重要，但我还想按属性/组名称或其他代码进行组织，以便最终得到由两者组织的多个 API 定义。

版本控制代码很简单：

foreach (var description in provider.ApiVersionDescriptions)
{
     options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
}

理想情况下，它将类似于以下内容：

foreach (var tag in some_variable_that_contains_tags_or_something)
{
     foreach (var description in provider.ApiVersionDescriptions)
     {
         options.SwaggerEndpoint($"/swagger/{tag}/{description.GroupName}/swagger.json", tag + " " + description.GroupName.ToUpperInvariant());
     }
}

这将由控制器上的某些东西驱动，例如：

[ApiController]
[Tag("Tag Example")] -- Will drive the tag/attribute/something list when creating definitions
[ApiVersion("1.0")]
[EnableCors("CorsPolicy")]
[Route("sample/v{version:apiVersion}")]
public class SampleController : ControllerBase

任何人都可以提供的任何帮助将不胜感激！

4

1 回答 1

1

您尝试实现的目标在技术上是可行的，但 OpenAPI（以前的 Swagger）UI 本质上并不支持这种行为。UI 由单个下拉菜单驱动。此限制意味着您只能在单个维度上进行分区。添加 API 版本控制后，分组自然会按 API 版本进行。在不改变一堆东西的情况下，最实用的解决方案是合并两个维度，这样你就会有Tag1-V1、Tag2-V1、Tag1-V2、Tage2-V2等等。如果您愿意提供自己的 UI，那么您就有更多的选择和灵活性。

还值得注意的是，API Explorer API 只有一个级别的组织，通过ApiDescription.GroupName. Swashbuckle 和 NSwag 等 OpenAPI 文档生成器使用它来驱动组织，并且最终将文档与下拉列表结合起来。支持多个维度也需要一些额外的定制，因为 API 被分桶到ApiDescriptionGroup，它只有一个级别的分组：ApiDescriptionGroup.GroupName.

我在68788850中提供了更深入的解释和解决方案。我还建议您使用[ApiExplorerSettings(GroupName = "{Tag}")]而不是创建自己的属性。如果您愿意，您当然可以使用自己的属性，但这可能只是增加了额外的、不必要的工作。

如果这不能充分回答您的问题，我可以进一步详细说明。

于 2022-01-25T21:24:06.930 回答