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

Question

我想合并使用 OpenAPI 3 规范编写的 API 规范，该规范当前分为多个使用 $ref 相互引用的文件。我该怎么做？

Answer 1

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

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

npm install speccy -g

然后运行:

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

Answer 2

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

如果您特别需要获取单个解析文件，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 工具：

为了使用 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"
}

有关详细信息，请参阅 README on the NPM package。

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

How do I combine multiple OpenAPI 3 specification files together?

api

swagger

openapi

OpenAPI 3.0 示例

OpenAPI 2.0 示例