Swashbuckle、多个 API 版本和虚拟目录

Question

我正在考虑使用 Swashbuckle/Swagger 来记录我的 WebAPI 解决方案。开发者门户类似于https://myapi.com/，而版本化API 是https://myapi.com/v1/users。

URL 的版本部分映射到一个虚拟目录，其中包含 v1 的二进制文件和配置文件。当版本 2 发布时，我们在根目录下创建了一个新的虚拟目录，所以现在我们有了 https://myapi.com/v2/users/some_new_endpoint_not_in_v1。这意味着除了错误修复之外，无需触及任何旧版本的二进制文件，从而减少了某些开发人员意外破坏我们客户的向后兼容性的可能性。

但是，我看不到如何配置 Swashbuckle 以查看这些虚拟目录以获取控制器/操作和 XML cmets 进行解析。 MultipleApiVersions 配置选项似乎更针对将所有支持的版本放入一组二进制文件（通过命名空间或控制器名称）而不是将它们分成单独的进程的人。

关于如何让 Swashbuckle 按我的意愿弯曲有什么建议吗？我是否应该将 Swashbuckle 作为单个 API 版本安装到各个虚拟目录中，这样文档就变成了 https://myapi.com/v1/swagger 之类的东西？然后，我的门户会做必要的工作来公开不同的 API 版本。

更新

我确实尝试了后一种方法，至少对于文档来说，它工作正常。问题是 Swagger 规范的 URL 然后变为 https://myapi.com/v1/swagger/docs/v1，我宁愿在 URL 中没有第二个 v1。不幸的是，Swaashbuckle 至少希望版本号在相对路径中，而不是在基本 URL 中。

Answer 1

这些都行：

• Swagger UI 在您的 API 站点的根目录下（与 Swashbuckle 无关），
• 您的版本的多个虚拟目录（“v1”、“v2”...）

要实现这一点：

• Swagger UI javascript 中的自定义 discoveryPaths 数组如下所示，添加了“/spec”后缀（或任何适合您的名称，因为 SwashBuckle 不处理具有空版本值的 c.SingleApiVersion ):

var currentUrl = 'https://myapi.com/';
window.swashbuckleConfig = {
    rootUrl: currentUrl,
    discoveryPaths: arrayFrom('v1/swagger/docs/spec|v2/swagger/docs/spec'),
    booleanValues: arrayFrom('true|false'),
    validatorUrl: stringOrNullFrom('null'),
    // other settings ommitted for brevity.
    oAuth2AdditionalQueryStringParams: JSON.parse('{}')
};

• 从您的 Web API 子应用中删除 c.EnableSwaggerUi