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

Question

我正在考虑使用 Swashbuckle/Swagger 来记录我的 WebAPI 解决方案。开发人员门户类似于 https://myapi.com/, while the versioned API is https://myapi.com/v1/users.

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

但是，我看不到如何配置 Swashbuckle 以查看那些虚拟目录以获取要解析的 controllers/actions 和 XML 注释。 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 中的自定义 discoveryPaths 数组 UI javascript 如下所示，添加了“/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

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

Swashbuckle, multiple API versions, and virtual directories

asp.net-web-api

swashbuckle