如何使用Swagger 2.0将API文档拆分为多个文件

根据Swagger 2.0规范，这样做是可能的。我使用$ref引用PathObject，它指向另一个文件。我们曾经能够使用Swagger 1.2很好地实现这一点。但Swagger UI似乎无法读取另一个文件中引用的PathObject

规范的这一部分是否太新，还不受支持？有没有办法将每个“路径”的文档拆分成另一个文件

{
    "swagger": "2.0",
    "basePath": "/rest/json",
    "schemes": [
        "http",
        "https"
    ],
    "info": {
        "title": "REST APIs",
        "description": "desc",
        "version": "1.0"
    },
    "paths": {
        "/time": {
            "$ref": "anotherfile.json"
        }
    }
}

---

虽然从理论上讲，将来可以这样做，但解决方案仍然没有完全融入到支持工具中，所以现在我强烈建议将其保存在一个文件中

---

如果您正在寻找一种管理和导航Swagger定义的方法，我建议使用规范的YAML格式，您可以在其中添加注释，这可能会简化大型定义的导航和拆分。

您还可以使用JSON Refs库来解析此类多文件Swagger规范

我已经在报纸上写过了

---

还需要演示所有这些是如何工作的。

要支持多个文件，您的库必须支持取消引用

$ref

字段。但我不建议交付包含未解析引用的swagger文件。我们的狂妄定义大约有30-40个文件。通过HTTP/1.1交付它们可能会降低任何阅读应用程序的速度

因为我们也在构建javascript库，所以我们已经有了一个使用gulp的基于nodejs的构建系统。对于节点包管理器（npm），您可以找到一些支持取消引用以构建一个大文件的库

我们的基本文件如下所示（缩短）：

swagger:'2.0'
信息：
版本：2.0.0
标题：应用程序
描述：示例
基本路径：/api/2
路径：
$ref:“routes.json”
定义：
例子：
$ref:“schema/example.json”

routes.json

是从我们的路由文件生成的。为此，我们使用了一个吞咽目标，实现方式如下：

var gulp=require（'gulp'）；
var fs=需要（'fs'）；
var gutil=require（'gulp-util'）；
var swagger-jsdoc=require（'swagger-jsdoc'）；
吞咽任务（'routes-swagger'，[]，函数（完成）{
变量选项={
大摇大摆的定义：{
信息：{
标题：“仅路线，不使用，仅供参考”，
版本：“1.0.0”，
},
},
API:['./routing.php']，//API文档的路径
};
var swaggerSpec=swaggerJSDoc（选项）；
fs.writeFile（'public/doc/routes.json'，json.stringify（swaggerSpec.path，null，“\t”），函数（错误）{
如果（错误）{
日志（gutil.colors.red（错误））；
}否则{
log（gutil.colors.green（“成功生成的路由包括”）；
完成（）；
}
});
});

为了生成swagger文件，我们使用一个构建任务，实现如下：

var gulp=require（'gulp'）；
var bootprint=require（'bootprint'）；
var bootprintSwagger=require（'bootprint-swagger'）；
var swagger-parser=require（'swagger-parser'）；
var gutil=require（'gulp-util'）；
var fs=需要（'fs'）；
吞咽任务（'swagger'，['routes-swagger'，函数（）{
SwaggerParser.bundle（'public/doc/swagger.yaml'{
“缓存”：{
“fs”：错误
}
})
.then（函数（api）{
fs.writeFile（'public/doc/swagger.json'，json.stringify（api，null，“\t”），函数（错误）{
如果（错误）{
日志（gutil.colors.red（错误））；
}否则{
log（“捆绑的API%s，版本：%s”，gutil.colors.magenta（API.info.title），API.info.Version）；
}
});
})
.catch（函数（err）{
log（gutil.colors.red.bold（err））；
});
});

---

通过这个实现，我们可以维护一个相当大的招摇过市规范，并且我们不局限于特殊的编程语言或框架实现，因为我们在注释中定义了真正路由定义的路径。（注意：gulp任务也分为多个文件。）

如果现在可以，您能更新一下吗？如果是，请指出正确的文档/参考实施？