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

Question

根据Swagger website，有两种方法：自下而上和自上而下。

我有一个想要在 Azure 环境中部署的现有 NodeJS 服务器，它需要一个招摇文档（API APP）。

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

Answer 1

大多数替代方案需要通过 Json、Yaml 甚至嵌入 JSdocs 的某种 API 规范。另一方面，有一些运行时分析器会拦截 HTTP 请求并按需构建该规范。

express-sitemap-html 采用不同的方法在设置时检查 express 对象及其路由。因此，它始终为现有 express 实例上已安装的路由提供最新的 swagger UI。

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Title', app) // app is an express instance

然后从您的域/api-docs 获取 Swagger UI。

Answer 2

很多开发人员仍然遇到这个问题，所以我构建了一个开源工具来提供帮助——该工具有点像用于 API 的 Git。它的工作原理是在您开发 API、分析流量并随着 API 行为的变化为您更新规范时运行代理。希望该工作流程可以为您节省大量时间：https://github.com/opticdev/optic

Answer 3

问题有点老了，但仍然存在。只需像这样嵌入分析中间件，就可以完全自动生成 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

Answer 4

据我所知，您的选择是：

1. 使用swagger-node-express 在我看来非常麻烦。
2. 在swagger editor 的帮助下自己手动编写swagger 文档，正如SO Answer 中所建议的那样

如果您选择选项 2，则可以使用 swagger-ui-express 生成 swagger-ui

Answer 5

在this tutorial 之后，将 Swagger 集成到现有的 express 应用程序中并不难。

一般情况下，我们可以按照以下步骤进行：

1. 在我们的package.json 中添加依赖项，然后运行npm install 来安装它们。依赖项应该是：

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

2. 下载Swagger-UI的zip项目，将dist文件夹复制到我们项目的根目录下，目录应该是这样的：

1. 在app.js开头引入依赖：

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

2. 为swagger doc设置子路径：

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

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

4. 设置 API 信息：

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

5. 为 Swagger UI 引入/dist/index.html：

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

6. 完成swagger配置：

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

7. 在/dist/index.html中配置doc文件依赖：

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

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

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

这是我的test sample repo 供您参考。