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

Question

根据 Swagger 网站 的介绍，有两种方法：自下而上和自上而下。

我有一个现有的 NodeJS 服务器，希望将其部署在 Azure 环境中，需要一个 Swagger 文档（API 应用程序）。

有没有人知道一个可以使用代码生成 Swagger 的工具？最好能够指导一个教程。我找不到它。

- Ernani

---

你的 Node.js 服务器使用了哪个框架？如果是 Express 的话，你可以参考 https://github.com/shawngong/Swagger-Node-Express-For-Existing-APIs。若想将 Node.js 应用部署到 Azure Web Apps，请参考 https://azure.microsoft.com/zh-cn/documentation/articles/web-sites-nodejs-develop-deploy-mac/。 - Gary Liu

@GaryLiu-MSFT 是的，我使用了 Express。我尝试了你发送的这个项目，但我并没有真正理解它。在教程中，它告诉你要准备所有东西，还有很多代码，然后它并没有说生成 Swagger 文档应该怎么做... - Ernani

我认为你可以先按照逐步教程构建Swagger文档，或者你能告诉我哪一步阻碍了你吗？ - Gary Liu

也许你需要这样的东西？http://mherman.org/blog/2016/05/26/swagger-and-nodejs/#.WZ7LQCgjHIU 根据这个链接，你可以使用模块“swagger-jsdoc”从你的项目中生成Swagger文档。 - Margarita Krivorot

Answer 1

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

- mpashkovskiy

---

嗨，感谢提供的信息。我也在使用express-oas-generator来生成API文档，它能够正常工作，但有时候在响应中更新后，UI界面并没有及时更新。您能帮忙解决这个问题吗？ - s.chandran sha

当然，我可以请您在此处创建一个问题并详细描述问题：https://github.com/mpashkovskiy/express-oas-generator/issues？ - mpashkovskiy

你好，你是express-oas-generator的创建者吧。我很喜欢它并在我的Express应用程序中使用它。我想要的一个功能是像Fastify那样动态填充body、headers、query等内容。就像添加一个中间件函数，将架构作为其参数传递，并将其传递给OAS Gen。有计划在未来版本中添加这个功能吗？ - Mr. X

Answer 2

按照这个教程，在已有的express应用程序中集成Swagger不难。

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

1. 将相应依赖项添加到我们的package.json文件中，并运行npm install安装它们。依赖项应包括：

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

2. 下载Swagger-UI的zip项目，将dist文件夹复制到我们项目的根目录下，目录结构应该类似于：

3. 在app.js的开头引入相关依赖：

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

设置Swagger文档的子路径：

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

确保在express中，/dist可以用来提供静态文件： app.use(express.static('dist'));

设置API的信息：

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

介绍 /dist/index.html 用于 Swagger UI：

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

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

在/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-docs.json的文件，其中包含API的信息，并将其放在dist文件夹中。

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

这是我测试示例存储库可供参考。

- Gary Liu

---

这并不会“生成”任何内容，它只是在应用程序旁提供 SwaggerUI。 - Tony Gutierrez

我使用 https://www.npmjs.com/package/express-swagger-export 包从我的 express 3 应用程序生成了简单的 swagger.json，以便通过 Postman 应用程序导入。我为自己构建了它，但也许对其他人有用。 - Vlad Tsepelev

Swagger编辑器会在使用了“swagger项目编辑器”之后继续工作吗？ - user8193619

因为它不是自动生成的，而是需要手动操作，所以我会给它踩个负评。虽然并不难理解，但也不属于“轻松简单”的工作。 - Елин Й.

Answer 3

很多开发者仍然存在这个问题，因此我构建了一个开源工具来帮助解决——这个工具有点像API的Git。它通过在您开发API时运行代理，分析流量，并在API行为更改时更新规范。希望这种工作流程能够为您节省大量时间：https://github.com/opticdev/optic。

- centree

Answer 4

大多数替代方案都需要通过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。

- Miguel Gamboa

---

请问您能否帮忙澄清一下，为什么生成的路由看起来是/apiauth和/apiuser而不是/api/auth和/api/user？ - Mike Datsko

嗨，@MikeDatsko，我不明白你的疑问。你可以查看https://github.com/fmcarvalho/express-sitemap-html存储库中提供的示例。使用`node example\app.js运行它，然后你可以在http://localhost:3000/sitemap`或`http://localhost:3000/api-docs/#/`中检查站点地图。 - Miguel Gamboa

是的，我像示例中那样做了，并且这就是我在那里看到的 https://www.dropbox.com/s/9erszn17rf4v446/Screenshot.png?dl=0 - Mike Datsko

你在哪一行找到了具有路径auth或user的路由？https://github.com/fmcarvalho/express-sitemap-html/blob/master/example/app.js - Miguel Gamboa

你示例代码和我的不同之处在于我使用了 app.use，这可能是问题的根本原因吗？ - Mike Datsko

Answer 5

据我所知，您有以下选择：

1. 使用 swagger-node-express，但我认为这很繁琐。
2. 借助 swagger editor 的帮助手动编写 swagger 文档，就像在这个SO Answer中建议的那样。

如果您选择了第二个选项，您可以使用swagger-ui-express生成 swagger-ui。

- Ahmad Abdelghany