为现有的NodeJS服务器生成Swagger文档

问题描述：

根据 Swagger网站，有两种方法:自下而上和自上而下.

According to Swagger website, there are two approaches: Bottom-up and Top-down.

我有一个现有的NodeJS服务器，我想在Azure环境中部署该服务器，该服务器需要一个庞大的文档(API APP).

I have an existing NodeJS server that I'd like to deploy in the Azure enviroment, that require a swagger document (API APP).

有人知道使用该代码生成摇摇欲坠的工具吗?如果您可以指点教程，那就更好了.我找不到.

Does anyone know a tool for generating the swagger using the code? Even better if you could point a tutorial. I couldn't find it.

答

在通常，我们可以按照以下步骤操作:

Generally, we can follow these steps:

在我们的package.json中添加依赖项，然后运行npm install进行安装.依赖关系应为:

Add the dependencies in our package.json, and run npm install to install them. The dependencies should be:

"dependencies": {
        "swagger-node-express": "~2.0",
        "minimist": "*",
        "body-parser": "1.9.x",
        ...
}

下载 Swagger-UI 的zip项目，复制文件夹进入我们项目的根目录，该目录几乎应该像这样:

Download the zip project of Swagger-UI, copy the dist folder into the root directory of our project, the directory should almost like:

在app.js开头介绍依赖项:

var argv = require('minimist')(process.argv.slice(2));
var swagger = require("swagger-node-express");
var bodyParser = require( 'body-parser' );

为swagger文档设置子路径:

Set up a subpath for swagger doc:

var subpath = express();
app.use(bodyParser());
app.use("/v1", subpath);
swagger.setAppHandler(subpath);

确保/dist能够以快速方式提供静态文件: app.use(express.static('dist'));

Make sure that /dist is able to serve static files in express: app.use(express.static('dist'));

设置API信息:

swagger.setApiInfo({
    title: "example API",
    description: "API to do something, manage something...",
    termsOfServiceUrl: "",
    contact: "yourname@something.com",
    license: "",
    licenseUrl: ""
});

为swagger UI引入/dist/index.html:

subpath.get('/', function (req, res) {
    res.sendfile(__dirname + '/dist/index.html');
});

完成招摇式配置:

Complete the swagger configurations:

swagger.configureSwaggerPaths('', 'api-docs', '');

var domain = 'localhost';
if(argv.domain !== undefined)
    domain = argv.domain;
else
    console.log('No --domain=xxx specified, taking default hostname "localhost".');
var applicationUrl = 'http://' + domain;
swagger.configure(applicationUrl, '1.0.0');

在/dist/index.html中配置doc文件依赖项:

Configure doc file dependence in /dist/index.html:

if (url && url.length > 1) {
    url = decodeURIComponent(url[1]);
} else {
    <del>url = "http://petstore.swagger.io/v2/swagger.json";</del>
    url = "/api-docs.json";
}

使用您的API信息创建api-docs.json文件，并将其放在dist文件夹中.

Create api-docs.json file with the info of your APIs, put it in the dist folder.

在本地运行Express应用，请访问http://localhost:3000/v1，我们可以检查相应的文档.

Run the Express app on local, visit http://localhost:3000/v1, we can check the swagger doc.

这是我的测试示例存储库供您参考.

为现有的NodeJS服务器生成Swagger文档

相关推荐