如何将swagger 2.0的JSON文件分解成多个模块
我试图把我的API文档分解成多个可以独立编辑的JSON文件。 我所能find的所有示例都使用Swagger 1.2模式，它具有“api”：{}对象来分解它。 这似乎是从2.0架构（ http://json.schemastore.org/swagger-2.0 ）丢失。 所有定义的是一个单一的“path”数组，它将所有API端点绑定到单个数组中。 这在swagger-ui中的效果是有一个单一的“默认”类别，所有东西都捆绑在一起，我不能分辨出来。
TLDR：你如何将操作从swagger 2.0模式中的path中分离出来
{ "swagger": "2.0", "info": { "description": "My API", "version": "1.0.0", "title": "My API", "termsOfService": "http://www.domain.com", "contact": { "name": "support@domain.com" } }, "basePath": "/", "schemes": [ "http" ], "paths": { "Authorization/LoginAPI": { "post": { "summary": "Authenticates you to the system and produces a session token that will be used for future calls", "description": "", "operationId": "LoginAPI", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "parameters": [{ "in": "formData", "name": "UserName", "description": "Login Username", "required": true, "type": "string" }, { "in": "formData", "name": "Password", "description": "Password", "required": true, "type": "string" }], "responses": { "200": { "description": "API Response with session ID if login is allowed", "schema": { "$ref": "#/definitions/Authorization" } } } } } } } 你其中一个问几个问题，我会尽量回答他们。
在Swagger 1.2和之前，文件拆分是强制性的和人为的。 这意味着作为一种组织运作的方式，Swagger 2.0提供了另一种方法来做到这一点（不久将更多）。
Swagger 2.0确实是一个单一的文件，允许使用$ref外部文件。 您不能将单个服务拆分为多个文件并将它们合并为一个文件，但可以在外部指定特定path的操作（同样，使用$ref属性）。
目前，我们正在最终确定将多个微服务整理成一个集合的能力，但最终每个微服务仍然是一个单一的文件。
如前所述，Swagger 2.0中的操作分组已经改变，“资源”的概念不复存在。 相反，有标签（与"tags"财产）可以分配每个操作。 tags是一个值的数组，与以前的版本不同，如果需要，每个操作可以存在于多个标签下。 在Swagger-UI中，没有定义标签的所有操作都将以default标签结束，这就是你所看到的行为。 顶级对象还有一个额外的tags属性，允许您向标签添加说明并设置其顺序，但不一定要包含它。
最后，我不知道Swagger 2.0的json模式是如何在http://json.schemastore.org/swagger-2.0结束的，但是肯定不是最新的。; 最新的模式可以在这里find – http://swagger.io/v2/schema.json – 它仍在开发中。 请记住，真相的来源是规范（ https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md ），而不是模式，所以如果发生冲突，规格“胜利”。
编辑：
我们刚刚发布了参考指南。 它可以帮助一些用例 – https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md
我在这篇博客文章中已经写了这个。 你基本上可以使用JSON Refs库来解决所有你的小Swagger文件到一个大的一个，并在工具中使用它。
如果JSON文件不适合你，编写你自己的连接器可能是有用的。 那么，而不是写自己的，你可以实际上使用已经在那里的东西。 任何模板引擎都可以。 在我看来，Handlebars非常有帮助（因为Handlebars实际上保留了缩进，这对于Yaml文件来说是完美的，因为它们区分大小写）。
那么你可以在Node中有一个构build脚本：
'use strict'; var hbs = require('handlebars'); var fs = require('fs'); var dir = __dirname + '/your_api_dir'; var files = fs.readdirSync(dir); files.forEach((fileName) => { var raw = fs.readFileSync(dir + '/' + fileName, 'utf8'); hbs.registerPartial(file, raw); }); var index = fs.readFileSync(dir + '/index.yaml'); var out = hbs.compile(index.toString());
在我的博客上阅读更多关于这个问题。
请注意， RepreZen API Studio现在通过这里讨论的$ref语法支持多文件Swagger / Open API项目。 因此，您可以将大型Swagger项目分解为模块，以便重用和团队协作。 然后，您可以使用内置的Swagger规范化器创build一个统一的Swagger文件，当您需要将API模型超出devise/开发环境时。
注：为了充分披露，我是RepreZen的产品经理。 我上周偶然发现了这个主题，并认为我会陷入困境。
我也想弄清楚，在Swagger Google小组中有一些有用的信息。 看起来像共识是，只要$ ref指向一个绝对的url，你可以将定义分解成单独的文件。 示例：
如果json不为你工作，你也可以使用node.js，也可以使用module.exports
我有我的定义在模块中，我可以要求一个模块内的模块：
const params = require(./parameters); module.exports = { description: 'Articles', find: { description: 'Some description of the method', summary: 'Some summary', parameters: [ params.id, params.limit, ...
