OpenAPI - 从外部文件引用路径

Question

我正在尝试使用 swagger-ui-express 和 yaml 包来记录我的expressJS API以解析yaml文件。

这是我的文件结构的相关部分：

└── doc
   ├── test.yaml
   └── openapi.yaml

在根打开 api 文件 (openapi.yaml) 中，我尝试引用另一个文件中的路径。

这是我的根 openapi.yaml 文件：

openapi: 3.0.0
info: 
  ...
servers:
  ...
paths:
  /test:
    $ref: "./test.yaml#/test"

这是我的 test.yaml 文件：

/test:
  post:
    summary: A test endpoint.
    responses:
      "200": 
        description: A test endpoint. 

但是 swagger ui 显示了这个错误：

Could not resolve reference: Could not resolve pointer: /test does not exist in document

我也尝试过：

$ref: "./test.yaml#/~1test"

但我得到了基本上相同的错误。

如果我尝试：

• $ref：“./test.yaml”
• $ref：“./test.yaml#”

我没有收到任何错误，但我的

/test

的信息都没有指向。

如果我在

/test

中包含

openapi.yaml

路径数据，那么它就可以正常工作，但我想模块化我的 api 文档。

我应该如何在 openapi.yaml 中引用外部文件的路径？

Answer 1

这看起来像是 swagger UI 中的一个错误，在我看来，

$ref: "./test.yaml#/~1test"

语法应该可以工作。

从

test.yaml

中删除前导斜杠是否是一种可行的解决方法，例如

test:
  post:
    summary: A test endpoint.
...

然后用

$ref: "./test.yaml#/test"

引用它？我的意思是，在

test.yaml

中，

/test

键实际上只是您用于引用的名称，所以它应该不会太重要。