Swashbuckle 生成的 Swagger 在 Azure API 管理中创建重复的版本路径

Question

我正在尝试将 Azure API 管理配置为使用版本控制，并使其与 Swashbuckle 生成的 Swagger / Open API 文档一起使用。

我的 API 有 2 个版本 - 1.0 和 2.0。我已将 Swashbuckle 配置为生成 2 个单独的 Swagger 文档，每个版本一个。都很好。

版本控制方案是按路径的，因此消费者需要调用正确的路径（v1.0 或 v2.0）。像这样：https://someurl/v1.0/some/thing

我在 Azure API 管理中定义了这两个版本并导入了这两个文档。

问题在于 Azure API 管理正在添加基本 URL 的路径，然后因为在 Swashbuckle 生成的开放 API 文档中定义的路径，我最终在 Azure API 管理中得到了https://someurl/v1.0/v1.0/some/thing。

下面是生成的 Swagger / Open API 的 sn-p...

以及 Azure API 管理中的 API 版本设置...

以及 Azure API 管理中的完整 URL...

所以，我的问题是如何使用 Swashbuckle 或任何其他工具生成 Swagger 文档，以便我可以使用路径版本控制方案支持 Azure API 管理版本控制。

提前谢谢你！

Answer 1

由于 OpenAPI 规范本身不允许您定义版本控制方案，因此无法在 APIM 级别推断用户意图。一个人可能希望在路径中将带有 /v1.0/ 的 API 作为单个 API 导入，而其他人（例如您的情况）想要设置 API + 版本。 APIM 默认不会在 API 导入期间创建/更新版本集，因此目前唯一的方法是在导入 APIM 之前从 OpenAPI 规范中删除 /v1.0 前缀。

APIMs 域模型允许在 API 版本集级别控制版本控制方案（路径前缀、标头名称/值、查询参数名称/值），因此您无需在每次操作时都复制 /v1.0你的 API。从本质上讲，如果您的 API 版本集配置为具有 /v1.0 的路径前缀，它将被附加到包含在此版本集中的所有 API 路径中。这就是导致翻倍的原因。