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

Question

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

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

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

Answer 1

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

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

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

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

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

3. 在qazxsw poi的开头介绍依赖关系： qazxsw poi
4. 为swagger doc设置子路径： app.js
5. 确保

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

   能够在express：

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

   中提供静态文件
6. 设置API的信息： /dist
7. 介绍app.use(express.static('dist'));的swagger UI：

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

8. 完成招摇配置： /dist/index.html
9. 在qazxsw poi中配置doc文件依赖： qazxsw poi
10. 使用API​​的信息创建

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

    文件夹中。

在本地运行Express应用程序，访问/dist/index.html，我们可以查看swagger 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";
}

供您参考。

Answer 2

问题有点陈旧但仍然存在。只需嵌入分析中间件就可以完全自动生成Swagger（OpenAPI）规范：api-docs.json

dist

运行一些客户端针对您的服务进行REST API测试并打开qazxsw poi

Answer 3

据我所知，您的选择是：

1. 使用http://localhost:3000/v1在我看来非常麻烦。
2. 根据test sample repo的建议，在https://github.com/mpashkovskiy/express-oas-generator的帮助下手动自己写出招摇文件

如果你选择2，你可以使用

const express = require('express');    
const expressOasGenerator = require('express-oas-generator');
let app = express();
expressOasGenerator.init(app, {});

来生成swagger-ui