为了支持多个文件,您的库必须支持解析
$ref
字段。但我不建议使用未解析引用的方式提供swagger文件,因为我们的swagger定义大约有30-40个文件。通过HTTP/1.1传送这些文件可能会减慢任何阅读应用程序的速度。
由于我们也正在构建JavaScript库,我们已经使用gulp基于nodejs构建了一个构建系统。对于Node包管理器(npm),您可以找到一些支持解析引用以构建一个大的swagger文件的库。
我们的基本文件如下所示(缩短):
swagger: '2.0'
info:
version: 2.0.0
title: App
description: Example
basePath: /api/2
paths:
$ref: "routes.json"
definitions:
example:
$ref: "schema/example.json"
routes.json
是从我们的路由文件生成的。为此,我们使用一个实现了 swagger-jsdoc 的 gulp 目标,如下所示:
var gulp = require('gulp');
var fs = require('fs');
var gutil = require('gulp-util');
var swaggerJSDoc = require('swagger-jsdoc');
gulp.task('routes-swagger', [], function (done) {
var options = {
swaggerDefinition: {
info: {
title: 'Routes only, do not use, only for reference',
version: '1.0.0',
},
},
apis: ['./routing.php'],
};
var swaggerSpec = swaggerJSDoc(options);
fs.writeFile('public/doc/routes.json', JSON.stringify(swaggerSpec.paths, null, "\t"), function (error) {
if (error) {
gutil.log(gutil.colors.red(error));
} else {
gutil.log(gutil.colors.green("Succesfully generated routes include."));
done();
}
});
});
为了生成Swagger文件,我们使用一个实现SwaggerParser的构建任务,如下所示:
var gulp = require('gulp');
var bootprint = require('bootprint');
var bootprintSwagger = require('bootprint-swagger');
var SwaggerParser = require('swagger-parser');
var gutil = require('gulp-util');
var fs = require('fs');
gulp.task('swagger', ['routes-swagger'], function () {
SwaggerParser.bundle('public/doc/swagger.yaml', {
"cache": {
"fs": false
}
})
.then(function(api) {
fs.writeFile('public/doc/swagger.json', JSON.stringify(api, null, "\t"), function (error) {
if (error) {
gutil.log(gutil.colors.red(error));
} else {
gutil.log("Bundled API %s, Version: %s", gutil.colors.magenta(api.info.title), api.info.version);
}
});
})
.catch(function(err) {
gutil.log(gutil.colors.red.bold(err));
});
});
通过这种实现方式,我们可以维护一个相当大的swagger规范,并且不受特定编程语言或框架实现的限制,因为我们将路径定义在对真实路由定义的注释中。(注意:gulp任务也分成多个文件。)