如何创建对其他子文件具有 $ref 的 OpenAPI 规范文件？这可能吗？

Question

我无法让 OpenAPI 规范 Swagger“外部引用”工作，因为 Swagger 渲染给了我一个例外。

我必须拥有这个才能使编辑巨大的swagger文档更易于管理，因为我没有自动生成器（由于azure sdk的架构）

我正在使用3.0.1版本，尝试做这样的事情：

paths:
  /v1:
    $ref: 'first-api.yaml#/paths/~1v1'
  /v2:
    $ref: 'second-api.yaml#/paths/~1v2'

这个问题的答案不起作用： 如何使用 $ref 引用另一个 OpenAPI 文件的路径？

我得到的错误看起来像这样（在 IntelliJ-IDEA IDE 中使用

OpenAI (Swagger) Editor

插件）：

希望能提供证明此方法有效的示例项目的链接。

例如，我在这里尝试过，但失败了：

• 主json：https://www.npoint.io/docs/1409525a51f14540ab0a
• 测试1 json：https://www.npoint.io/docs/ae1d3959a91b828a3098
• test2 json： https://www.npoint.io/docs/775e7edb2c1ccb01a735

Answer 1

改变

  "paths": {
    "/test": {
      "$ref": "https://api.npoint.io/ae1d3959a91b828a3098#/paths/test"
    },
    "/document": {
      "$ref": "https://api.npoint.io/775e7edb2c1ccb01a735#/paths/document"
    }
  },

到

  "paths": {
    "/test": {
      "$ref": "https://api.npoint.io/ae1d3959a91b828a3098#/paths/~1test"
    },
    "/document": {
      "$ref": "https://api.npoint.io/775e7edb2c1ccb01a735#/paths/~1document"
    }
  },

请注意，参考文献看起来像

...#/paths/~1test

而不是

...#/paths/test

。

~1

是路径项引用中使用的 转义字符。

修复后的版本在 Swagger Editor 中正确呈现：

Answer 2

尝试更改

$ref

以指定以对当前目录的显式引用开头的路径。也就是说，在路径前面加上

./

paths:
  /v1:
    $ref: './first-api.yaml#/paths/~1v1'