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

Question

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

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

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

Answer 1

在 this tutorial.

之后的现有 express 应用程序中集成 Swagger 并不难

一般来说，我们可以按照以下步骤进行：

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

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

下载Swagger-UI的压缩包，将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 能够以 express 方式提供静态文件： app.use(express.static('dist'));

设置 API 的信息:

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

引入/dist/index.html招摇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');

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

用你的 API 的信息创建 api-docs.json 文件，把它放在 dist 文件夹中。

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

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

Answer 2

据我所知，您的选择是：

使用 swagger-node-express 在我看来非常麻烦。
在 swagger editor as suggested in this SO Answer

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

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

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

Answer 5

大多数替代方案需要通过 Json、Yaml 或什至嵌入 JSdoc 的某种 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.

中大放异彩 UI

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

Generate Swagger Document for existing NodeJS server

api

azure

node.js

swagger

server