如何使用Swagger 2.0在多个文件中拆分API文档

时间:2015-03-27 04:57:09

标签: swagger

根据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"
        }
    }
}

3 个答案:

答案 0 :(得分:1)

要支持多个文件,您的库必须支持取消引用$ref字段。但我不建议使用未解析的引用来传递swagger文件。我们昂首阔步的定义有大约30-40个文件。通过HTTP / 1.1传送它们可能会减慢任何阅读应用程序。

由于我们正在构建javascript库,我们已经使用gulp构建了基于nodejs的构建系统。对于节点包管理器(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'], // Path to the API docs
    };
    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任务也分为多个文件。)

答案 1 :(得分:0)

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

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

答案 2 :(得分:0)

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

我在this blog post

中写过这篇文章

还有this GitHub repo来演示所有这些是如何工作的。