node.js 为现有的 NodeJS 服务器生成 Swagger 文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/33534488/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Generate Swagger Document for existing NodeJS server
提问by Ernani
According to Swagger website, there are two approaches: Bottom-up and Top-down.
根据Swagger 网站，有两种方法：自下而上和自上而下。
I have an existing NodeJS server that I'd like to deploy in the Azure enviroment, that require a swagger document (API APP).
我有一个现有的 NodeJS 服务器，我想在 Azure 环境中部署它，它需要一个 swagger 文档（API APP）。
Does anyone know a tool for generating the swagger using the code? Even better if you could point a tutorial. I couldn't find it.
有谁知道使用代码生成招摇的工具？如果你能指出一个教程就更好了。我找不到。
采纳答案by Gary Liu - MSFT
It's not difficult to integrate Swagger in exist express applications following this tutorial.
按照本教程将 Swagger 集成到现有的 Express 应用程序中并不困难。
Generally, we can follow these steps:
一般来说，我们可以按照以下步骤进行：
Add the dependencies in our
package.json, and runnpm installto install them. The dependencies should be:"dependencies": { "swagger-node-express": "~2.0", "minimist": "*", "body-parser": "1.9.x", ... }Download the zip project of Swagger-UI, copy the
distfolder into the root directory of our project, the directory should almost like:
在我们的 中添加依赖项
package.json，然后运行npm install以安装它们。依赖项应该是："dependencies": { "swagger-node-express": "~2.0", "minimist": "*", "body-parser": "1.9.x", ... }下载Swagger-UI的 zip 项目，将
dist文件夹复制到我们项目的根目录下，目录应该是这样的：
Introduce the dependencies at the beginnng of
app.js:var argv = require('minimist')(process.argv.slice(2)); var swagger = require("swagger-node-express"); var bodyParser = require( 'body-parser' );Set up a subpath for swagger doc:
var subpath = express(); app.use(bodyParser()); app.use("/v1", subpath); swagger.setAppHandler(subpath);Make sure that
/distis able to serve static files in express:app.use(express.static('dist'));Set the info for API:
swagger.setApiInfo({ title: "example API", description: "API to do something, manage something...", termsOfServiceUrl: "", contact: "[email protected]", license: "", licenseUrl: "" });Introduce
/dist/index.htmlfor swagger UI:subpath.get('/', function (req, res) { res.sendfile(__dirname + '/dist/index.html'); });Complete the swagger configurations:
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');Configure doc file dependence in
/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"; }Create
api-docs.jsonfile with the info of your APIs, put it in thedistfolder.
在开头引入依赖
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: "[email protected]", license: "", licenseUrl: "" });/dist/index.htmlswagger 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-docs.json使用您的 API 信息创建文件，将其放入dist文件夹中。
Run the Express app on local, visit http://localhost:3000/v1, we can check the swagger doc.
在本地运行 Express 应用程序，访问http://localhost:3000/v1，我们可以查看 swagger 文档。
Here is my test sample repofor your reference.
这是我的测试示例 repo供您参考。
回答by mpashkovskiy
Question is a bit old but still. It is possible to generate completely automatically Swagger (OpenAPI) specification just by embedding analysis middleware like this: https://github.com/mpashkovskiy/express-oas-generator
问题有点老，但仍然。只需像这样嵌入分析中间件，就可以完全自动生成 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, {});
run some client or REST API tests agains your service and open http://host:port/api-docs
再次对您的服务运行一些客户端或 REST API 测试并打开http://host:port/api-docs
回答by Ahmad Abdelghany
To my knowledge, your options are:
据我所知，您的选择是：
- Using swagger-node-expresswhich is very cumbersome in my opinion.
- Writing up the swagger document manually yourself with the help of swagger editoras suggested in this SO Answer
- 使用swagger-node-express在我看来非常麻烦。
- 按照此SO Answer 中的建议，在swagger 编辑器的帮助下自己手动编写 swagger 文档
If you go for option 2, you could use swagger-ui-expressto generate the swagger-ui
如果您选择选项 2，则可以使用swagger-ui-express生成 swagger-ui
回答by centree
A lot of developers are still having this problem so I built an open-source tool to help -- the tool is kind of like Git for APIs. It works by running a proxy while you're developing the API, analyzing the traffic, and updating the spec for you as the API's behavior changes. Hopefully, the workflow saves you a lot of time: https://github.com/opticdev/optic
许多开发人员仍然遇到这个问题，所以我构建了一个开源工具来提供帮助——这个工具有点像用于 API 的 Git。它的工作原理是在您开发 API、分析流量并在 API 行为发生变化时为您更新规范时运行代理。希望工作流程可以为您节省大量时间：https: //github.com/opticdev/optic
