OAS 包含内容

Question

美洲国家组织的新成员。有人可以建议您如何使用可包含在多个规范中的可重用文件（或片段）创建 OAS 规范吗？每个示例我都可以看到对同一规范中的组件的引用，但我希望它是一个单独的文件，以便它可以被多个规范引用。

Answer 1

使用 https://redocly.com/docs/cli |

npm i @redocly/cli

它是一个强大的工具箱，不仅仅是扩展的

$ref

s

它们支持文件系统中的相对路径，甚至支持引用（$refs）中的远程URL

当您的非标准参考定义完成后，只需捆绑将其取出

PS 查看所有其他非常有用的命令

Answer 2

引用可以是任何相对 URI。您找到的大多数示例都显示使用 URI 片段对同一文件的引用，即

#

（哈希）之后的所有内容，但您也可以在其前面放置内容，包括指向不同文件的路径。

例如：

# Pet.yml
Pet:
  type: object
  properties:
    name:
      type: string
      example: "doge"

# API.yml
...
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./Pet.yml#/Pet"

通过这种方式，您可以将规范拆分为多个文件（和文件夹），并在多个 API 规范中重复使用这些文件。

注意： 这假设是 OAS 版本 3，不确定它是否适用于以前的版本。