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

【问题标题】：How do I combine multiple OpenAPI 3 specification files together?如何将多个 OpenAPI 3 规范文件组合在一起？
【发布时间】：2019-02-08 04:52:53
【问题描述】：

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

【问题讨论】：

标签： api swagger openapi

【解决方案1】：

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

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

npm install speccy -g

然后运行：

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

【讨论】：

Speccy 不再积极维护

【解决方案2】：

我最近编写了一个快速工具来执行此操作。我称之为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。

【讨论】：

终于有人结合了多种规范，而不是“合并”$refs！非常感谢??

【解决方案3】：

大多数 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。

【讨论】：

我个人想不出使用codegen“组合”或“合并”多个输入定义的选项；你能举个例子吗？ -i swtich 接受单个输入 - 传递多个值的事件 (-i def1.json -i def2.json) 不起作用
@asceta 这个问答是关于当你有一个使用$ref 引用外部定义的“主”API 定义文件的情况。如果您的意思是要合并两个不同的 API 定义（具有不同的端点集、模式等），这是一个不同的用例，您应该 ask a new question。