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

Question

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

我有一个现有的NodeJS服务器,我想在Azure环境中部署,需要一个昂首阔步的文档(API APP).

有没有人知道使用代码生成招摇的工具？如果你能指出一个教程,那就更好了.我找不到它.

Answer 1

在本教程之后将Swagger集成到现有快速应用程序中并不困难.

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

1. 在我们中添加依赖项 package.json,然后运行npm install以安装它们.依赖项应该是:

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

2. 下载Swagger-UI的zip项目,将dist文件夹复制到我们项目的根目录中,该目录应该几乎像:

3. 在以下的beginnng中引入依赖项app.js:

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

4. 为swagger doc设置子路径:

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

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

6. 设置API的信息:

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

7. 介绍/dist/index.htmlswagger UI:

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

8. 完成招摇配置:

   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. 配置doc文件依赖/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. api-docs.json使用API​​的信息创建文件,将其放在dist文件夹中.

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

这是我的测试样本回购供您参考.

Answer 2

问题有点老，但是仍然。只需嵌入这样的分析中间件，就可以完全自动生成Swagger（OpenAPI）规范：https : //github.com/mpashkovskiy/express-oas-generator

const express = require('express');    
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {});

运行一些客户端或REST API测试再次服务，然后打开http：// host：port / api-docs