为现有的 NodeJS 服务器生成 Swagger 文档 [英] Generate Swagger Document for existing NodeJS server

问题描述

根据

3. 在app.js的开头引入依赖:

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

4. 为 swagger 文档设置子路径:

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

5. 确保 /dist 能够在 express 中提供静态文件:app.use(express.static('dist'));

6. 设置 API 信息:

   swagger.setApiInfo({标题:示例API"，描述:API 做某事，管理某事……"，termOfServiceUrl: "",联系方式:你的名字@something.com"，执照: ""，许可证网址:"});

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

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

8. 完成 swagger 配置:

   swagger.configureSwaggerPaths('', 'api-docs', '');var 域 = '本地主机';如果(argv.domain ！== 未定义)域 = argv.domain;别的console.log('没有指定 --domain=xxx，采用默认主机名localhost".');var applicationUrl = 'http://' + domain;swagger.configure(applicationUrl, '1.0.0');

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

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

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

在本地运行 Express 应用程序，访问 http://localhost:3000/v1，我们可以查看 swagger 文档.

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

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

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.

解决方案

It’s not difficult to integrate Swagger in exist express applications following this tutorial.

Generally, we can follow these steps:

1. 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",
           ...
   }
   

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

3. Introduce the dependencies at the beginnng of app.js:

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

4. Set up a subpath for swagger doc:

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

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

6. Set the info for API:

   swagger.setApiInfo({
       title: "example API",
       description: "API to do something, manage something...",
       termsOfServiceUrl: "",
       contact: "[e-mail]",
       license: "",
       licenseUrl: ""
   });
   

7. Introduce /dist/index.html for swagger UI:

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

8. 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');
   

9. 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";
   }
   

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

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

Here is my test sample repo for your reference.

这篇关于为现有的 NodeJS 服务器生成 Swagger 文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！