Question

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

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

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

Answer 1

将Swagger集成到this tutorial之后的现有快递应用程序中并不困难。

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

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

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

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

在app.js：

的beginnng处引入依赖项

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: ""
});

为swagger UI介绍/dist/index.html：

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

完成招摇配置：

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文档。

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

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

Answer 3

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

Answer 4

据我所知，您的选择是：

使用swagger-node-express，这在我看来非常麻烦。
根据swagger editor

SO Answer

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

Answer 5

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

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

5 个答案: