如何将多个OpenAPI 3规范文件组合在一起？

Question

我想结合使用OpenAPI 3规范编写的API规范，该规范当前分为使用相互引用的多个文件$ref。我怎样才能做到这一点？

Answer 1

一种方法是使用开源项目speccy。

打开终端并speccy通过运行安装（需要Node.js）：

npm install speccy -g

然后运行：

speccy resolve path/to/spec.yaml -o spec-output.yaml

Answer 2

大多数 OpenAPI 工具可以使用多文件 OpenAPI 定义并$ref动态解析s。

如果您特别需要获取单个解析文件，Swagger Codegen可以执行此操作。以下是 Swagger Codegen 命令行版本的使用示例。输入文件 ( -i) 可以是本地文件或 URL。

注意：为了便于阅读，添加了换行符。

OpenAPI 3.0 示例

使用Codegen 3.x解析 OpenAPI 3.0 文件：

java -jar swagger-codegen-cli-3.0.18.jar generate
     -l openapi-yaml
     -i ./path/to/openapi.yaml
     -o ./OUT_DIR
     -DoutputFile=output.yaml

-l openapi-yaml输出 YAML，-l openapi输出 JSON。

-DoutputFile是可选的，默认文件名是openapi.yaml/ openapi.json。

OpenAPI 2.0 示例

使用Codegen 2.x解析 OpenAPI 2.0 文件 ( swagger: '2.0')：

java -jar swagger-codegen-cli-2.4.12.jar generate
     -l swagger-yaml
     -i ./path/to/openapi.yaml
     -o ./OUT_DIR
     -DoutputFile=output.yaml

-l swagger-yaml输出 YAML，-l swagger输出 JSON。

-DoutputFile是可选的，默认文件名是swagger.yaml/ swagger.json。

Answer 3

我最近写了一个快速工具来做到这一点。我称之为 openapi-merge。有一个库和一个相关的 CLI 工具：

• https://www.npmjs.com/package/openapi-merge
• https://www.npmjs.com/package/openapi-merge-cli

为了使用 CLI 工具，您只需编写一个配置文件，然后运行npx openapi-merge-cli. 配置文件相当简单，看起来像这样：

{
  "inputs": [
    {
      "inputFile": "./gateway.swagger.json"
    },
    {
      "inputFile": "./jira.swagger.json",
      "pathModification": {
        "stripStart": "/rest",
        "prepend": "/jira"
      }
    },
    {
      "inputFile": "./confluence.swagger.json",
      "disputePrefix": "Confluence",
      "pathModification": {
        "prepend": "/confluence"
      }
    }
  ], 
  "output": "./output.swagger.json"
}

有关更多详细信息，请参阅NPM 包上的 README。