如何将swagger 2.0 JSON文件分解为多个模块

我试图将我的API文档分解为多个JSON文件，这些文件可以独立编辑。我能找到的所有示例都使用了Swagger 1.2模式，它有一个“api”：{}对象来分解它。2.0架构（）中似乎缺少的。定义的只是一个“路径”数组，它将所有API端点绑定到该数组中。在招摇过市的用户界面中，这样做的效果是，有一个“默认”类别，所有内容都被捆绑在其中，我无法告诉您如何将其拆分

TLDR：如何从swagger 2.0模式中的路径分割操作

{
“招摇过市”：“2.0”，
“信息”：{
“说明”：“我的API”，
“版本”：“1.0.0”，
“标题”：“我的API”，
“服务条款”：http://www.domain.com",
“联系人”：{
“名称”：support@domain.com"
}
},
“基本路径”：“/”，
“计划”：[
“http”
],
“路径”：{
“授权/登录”：{
“职务”：{
“摘要”：“向系统验证您的身份，并生成一个会话令牌，该令牌将用于将来的呼叫”，
“说明”：“，
“操作ID”：“LoginAPI”，
“消费”：[
“应用程序/x-www-form-urlencoded”
],
“生产”：[
“应用程序/json”
],
“参数”：[{
“in”：“formData”，
“名称”：“用户名”，
“说明”：“登录用户名”，
“必需”：正确，
“类型”：“字符串”
}, {
“in”：“formData”，
“名称”：“密码”，
“说明”：“密码”，
“必需”：正确，
“类型”：“字符串”
}],
“答复”：{
"200": {
“说明”：“如果允许登录，则使用会话ID的API响应”，
“模式”：{
$ref:“#/定义/授权”
}
}
}
}
}
}
}

实际上，您可以一次问几个问题，我将尝试全部回答

在Swagger 1.2及之前的版本中，文件拆分是强制性的和人为的。它的意思是作为一种分组操作的方式，而Swagger 2.0提供了实现这一点的替代方法（稍后会有更多介绍）

Swagger 2.0实际上是一个单独的文件，它允许在使用

$ref

的任何地方使用外部文件。您不能将单个服务拆分为多个文件并将它们合并为一个文件，但可以在外部指定特定路径的操作（同样，使用

$ref

属性）

我们目前正在完成将多个微服务整理成单个集合的功能，但最终，每个微服务仍将是单个文件

如前所述，Swagger 2.0中的操作分组已经改变，“资源”的概念不再存在。相反，有些标记（带有

“tags”

属性）可以为每个操作分配。

标记是一个值数组，与以前的版本不同，如果需要，每个操作可以存在于多个标记下。在Swagger UI中，所有未定义标记的操作都将在
默认值下结束，这就是您看到的行为。顶级对象中还有一个附加的
tags
属性，允许您向标记添加说明并设置其顺序，但不强制包含它

最后，我不知道Swagger 2.0的json模式是如何结束的，但它肯定不是最新的。最新的模式可以在这里找到，它仍在开发中。请记住，真相的来源是spec（），而不是schema，因此在发生冲突时，spec“获胜”

编辑：

我们刚刚出版了一本参考指南。它可能会对一些用例有所帮助-
我也在试图弄清楚这一点，在下面的文章中有一些有用的信息。看起来大家的共识是，只要$ref指向一个绝对url，就可以将定义分解成单独的文件。示例如下：


关于这一点，我已经在。基本上，您可以使用JSON ref库将所有小文件解析为一个大文件，并在工具中使用它。
如果JSON ref不适合您，那么编写自己的连接器可能会很有用。好吧，你可以使用已经存在的东西，而不是自己写。任何模板引擎都可以。在我的例子中，Handlebar非常有用（因为Handlebar实际上保留了缩进，这非常适合Yaml文件，因为它们区分大小写）

然后，您可以在节点中创建一个生成脚本：

“严格使用”；
var hbs=需要（“把手”）；
var fs=需要（'fs'）；
var dir=uuu dirname+'/您的_api_dir'；
var files=fs.readdirSync（dir）；
files.forEach（（文件名）=>{
var raw=fs.readFileSync（dir+'/'+文件名'utf8'）；
哈佛商学院注册部分（文件，原始）；
});
var index=fs.readFileSync（dir+'/index.yaml'）；
var out=hbs.compile（index.toString（））；

阅读有关此问题的更多信息。
注意，现在通过此处讨论的
$ref
语法支持多文件Swagger/Open API项目。因此，您可以将大型招摇过市项目分解为模块，以实现重用和团队协作。然后，当您需要将API模型移出设计/开发环境时，可以使用内置的Swagger normalizer创建一个统一的Swagger文件

注：为了充分披露，我是RepreZen的产品经理。上周我偶然发现了这个帖子，我想我应该插手一下。
如果json对你不起作用，你也可以使用node.js，你也可以使用
模块。导出

我在模块中有自己的定义，我可以要求模块中有一个模块：

const params = require(./parameters);
module.exports = {
  description: 'Articles',
  find: {
    description: 'Some description of the method', 
    summary: 'Some summary',
    parameters: [
        params.id,
        params.limit,


...

我编写了一个Swagger/OpenAPI预处理器来简化规范的编写


特别是它支持
$ref@Bean
public Docket module1() {
      return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.module1"))
        .paths(PathSelectors.any())
        .build()
        .groupName("module1")
        .apiInfo(apiInfo());
}