我正在尝试将我的API文档分解为多个可以独立编辑的JSON文件。我能够找到的所有示例都使用Swagger 1.2模式，该模式具有“api”：{}对象以便将其分解。这似乎在2.0模式（http://json.schemastore.org/swagger-2.0）中缺失。所有定义的都是单个“路径”数组，它将所有API端点捆绑到该单个数组中。这在swagger-ui中的效果是有一个单独的“默认”类别，所有内容都被捆绑在一起，我无法分辨它。
TLDR：如何从swagger 2.0模式中的路径中拆分操作
{
"swagger": "2.0",
"info": {
"description": "My API",
"version": "1.0.0",
"title": "My API",
"termsOfService": "http://www.domain.com",
"contact": {
"name": "[email protected]"
}
},
"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的任何地方使用外部文件。您不能将单个服务拆分为多个文件并将它们合并为一个，但您可以在外部指定特定路径的操作（同样，使用$ref属性）。
我们目前正在最终确定将多个微服务整理到一个集合中的能力，但最终，每个微服务仍然只是一个文件。
如前所述，Swagger 2.0中的操作分组已经改变，“资源”的概念已不复存在。相反，有些标签（带有"tags"属性）可以按操作分配。 tags是一个值数组，与以前的版本不同，如果需要，每个操作都可以存在于多个标记下。在Swagger-UI中，没有定义标签的所有操作都将在default标签下结束，这是您所见过的行为。顶级对象还有一个额外的tags属性，允许您向标记添加描述并设置它们的顺序，但不是必须包含它。
作为最后一点，我不知道Swagger 2.0的json-schema是如何在http://json.schemastore.org/swagger-2.0中结束的，但它肯定不是最新的。最新的架构可以在这里找到 - 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
我在this blog post写过这篇文章。您基本上可以使用JSON Refs库将所有小Swagger文件解析为一个大文件并在工具中使用它。
如果JSON ref不适合您，那么编写自己的连接器可能会很有用。好吧，你可以实际使用已经存在的东西，而不是自己编写。任何模板引擎都可以。在我的情况下，Handlebars非常有用（因为Handlebars实际上保留了缩进，这对于Yaml文件是完美的，因为它们区分大小写）。
然后你可以在Node中有一个构建脚本：
'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());
阅读有关on my blog问题的更多信息。
请注意，RepreZen API Studio现在通过此处讨论的$ref语法支持多文件Swagger / Open API项目。因此，您可以将大型Swagger项目分解为模块，以实现重用和团队协作。然后，当您需要将API模型带到设计/开发环境之外时，可以使用内置的Swagger规范化器创建单个整合的Swagger文件。
注意：为了充分披露，我是RepreZen的产品经理。我上周偶然发现了这个帖子，并且认为我已经填上了。
我也试图解决这个问题，并且在Swagger Google group中有一些有用的信息。看起来共识是，只要$ ref指向绝对URL，就可以将定义分解为单独的文件。这里的例子：
我写了一个Swagger / OpenAPI预处理器来简化规范的编写。
https://github.com/dolmen-go/openapi-preprocessor/
特别是它支持指向外部文件的$ref，并允许将您的规范编辑为多个文件，但生成单个文件以最大程度地兼容将使用它的工具。
如果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,
...