json - 如何在单个 swagger doc 文件中合并 swagger 多个文件？

Question

我为多个 API 提供了不同的 swagger 文件，例如用于 OpenStack API 的 swagger1.json、用于用户 API 的 swagger2.json 等，我试图使用远程 $ref 方法将这些所有 swagger 文件合并到一个文件中。

这是 OpenStack api 的 swagger1.json 文件

{
    "stacks": {
        "get": {
            "tags": [
                "openstack"
            ],
            "summary": "Returns stacks from OpenStack",
            "description": "Returns all stacks from the OpenStack based on tenantId.",
            "consumes": [
                "application/json"
            ],
            "produces": [
                "application/json"
            ],
            "parameters": [
                {
                    "in": "query",
                    "type": "string",
                    "name": "tenantId",
                    "description": "search stacks for tenantId from OpenStack",
                    "required": false
                }
            ],
            "responses": {
                "200": {
                    "description": "OK"
                },
                "400": {
                    "description": "Unknown Error"
                },
                "401": {
                    "description": "Unauthorized"
                }
            }
        }
    }

}

这是 swagger-merge.json，我想在其中使用远程引用添加多个 swagger doc 文件。

{
"swagger": "2.0",
"info": {
    "description": "something here",
    "version": "v0.7.0",
    "title": "The API Gateway",
    "contact": {
        "email": "[e-mail]"
    }
},
"host": "localhost",
"port":"9191",
"basePath": "/api/openstack",
"tags": [
    {
        "name": "OpenStackApi",
        "description": "Get stacks and running instance form OpenStack"
    }
],
"schemes": [
    "https"
],
"paths": {
    "$ref": "./swagger1.json#/stacks"
}

}

这对我不起作用。我看不到我在 swagger1.json 文件中编写的 API 方法。我已经上传了 swaggerUI 输出。关于我做错了什么以及如何解决这个问题的任何想法？

标签： jsonnode.jsswagger

Answer 1

你不能$ref完整的内容paths，你只能参考个别的路径项目：

"paths": {
   "/stacks": {    <--- endpoint path
     "$ref": "./swagger1.json#/stacks"
   }
}