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

Posted 2023-02-26

【中文标题】为现有的 NodeJS 服务器生成 Swagger 文档

【英文标题】：Generate Swagger Document for existing NodeJS server

【发布时间】：2016-02-05 16:38:17

【问题描述】：

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

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

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

【问题讨论】：

你的 Nodejs 服务器建立在哪个框架上？如果是快递，可以参考github.com/shawngong/Swagger-Node-Express-For-Existing-APIs。要将 Nodejs 应用部署到 Azure Web Apps，请参考azure.microsoft.com/en-us/documentation/articles/…

@GaryLiu-MSFT 是的，我使用了快递。我尝试了您发送的这个项目，但我无法真正理解它。在教程中它告诉你准备好所有东西，顺便说一下，很多代码，然后它没有说要做什么来生成swagger doc....

我认为您可以先按照分步教程先构建 swagger doc，或者您能告诉我是哪一步阻碍了您吗？

也许你需要这样的东西？ mherman.org/blog/2016/05/26/swagger-and-nodejs/#.WZ7LQCgjHIU据此，您可以使用模块'swagger-jsdoc'从您的项目中生成swagger doc。

【参考方案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。

【参考方案2】：

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

【参考方案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

【讨论】：

您好，感谢您提供的信息，我也在使用 express-oas-generator 使 api 文档正常工作，但作为响应，它有时不会在 ui 中更新，它有时会更新，您不能帮助修复问题

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

【参考方案4】：

据我所知，您的选择是：

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

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

【参考方案5】：

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

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

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

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

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

在app.js开头引入依赖：

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

为swagger doc设置子路径：

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

确保/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: ""
);

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

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中配置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";

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

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

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

【讨论】：

这不会“生成”任何东西。它只是在应用程序旁边提供 swaggerUI？

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

在swagger project editor 之后，Swagger 编辑器会使用这个吗？

投反对票，因为它不生成，它是手工工作，而不是“不难”。