node.js Swagger 可以根据现有的快递路线自动生成它的 yaml 吗？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/31300756/
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
Can Swagger autogenerate its yaml based on existing express routes?
提问by Manatax
I inherited an existing API and I would like to document it with swagger, but I don't yet know the full scope of it. Can Swagger (or another middleware/tool) auto-magically generate the yaml (for swagger) based on the existing express routes?
我继承了一个现有的 API，我想用 swagger 来记录它，但我还不知道它的全部范围。Swagger（或其他中间件/工具）能否根据现有的快速路由自动神奇地生成 yaml（用于 swagger）？
For what I saw on other questions, it would appear that this is mostly a manual job, but I'm double-checking if someone here found a way around this.
对于我在其他问题上看到的内容，这似乎主要是一项手动工作，但我正在仔细检查这里是否有人找到了解决方法。
回答by Mike
I have experience in BOTH auto-generating the Swagger json and manually writing it out for an API that I helped build. Here are the pros/cons of both based on my experience.
我在自动生成 Swagger json 和为我帮助构建的 API 手动编写它方面都有经验。根据我的经验，以下是两者的优缺点。
Swagger AUTOMATIC Documentation Generation:
Swagger 自动文档生成：
We used the swagger-node-express module in combination with swagger-ui.
https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
我们将 swagger-node-express 模块与 swagger-ui 结合使用。
https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
优点
Super easy to document. Just throw a few lines above the resource definition and the documentation (json) is automatically generated by the module.
超级容易记录。只需在资源定义上方抛出几行，模块就会自动生成文档 (json)。
Cons
缺点
You are no longer using straight up Express when you use this package. Your route definitions have to be defined through the Swagger module and this pulls you away from vanilla Express.
当您使用此软件包时，您不再直接使用 Express。你的路由定义必须通过 Swagger 模块定义，这会让你远离 vanilla Express。
Swagger MANUAL Documentation Generation:
Swagger 手册文档生成：
We just pulled swagger-ui into the project and wrote the documentation manually.
https://github.com/swagger-api/swagger-ui
我们只是将 swagger-ui 拉入项目并手动编写文档。
https://github.com/swagger-api/swagger-ui
Pros
优点
This approach decouples the documentation from the Express framework. Express endpoints are written as they normally would be written and the Swagger documentation is defined separate from the Express framework. Allows you to write pure express.
这种方法将文档与 Express 框架分离。Express 端点按照通常的方式编写，并且 Swagger 文档是独立于 Express 框架定义的。让你写出纯粹的快递。
Cons
缺点
Documentation changes become a little more tedious due to the fact that you are manually writing and changing the yaml or json yourself. It's a little bit harder than just updating a few lines of code above a resource. This approach is also a little more prone to documentation typos and errors due to the fact it is entirely manually typed.
由于您自己手动编写和更改 yaml 或 json，文档更改变得有点乏味。这比仅更新资源上方的几行代码要困难一些。由于它完全是手动输入的，因此这种方法也更容易出现文档拼写错误和错误。
If you are planning to manually write your swagger documentation use the swagger editor below to validate your manual docs.
http://editor.swagger.io/#/
如果您打算手动编写 swagger 文档，请使用下面的 swagger 编辑器来验证您的手动文档。
http://editor.swagger.io/#/
Conclusion
结论
For this API project, we started out by auto-generating the documentation using the swagger-node-express package. However, we realized that decoupling the swagger documentation from the express library was important to enable us to use all the features and functionality of Express. I recommend manually writing the docs to have full control over both the Swagger documentation and the Express web framework that your app will use.
对于这个 API 项目，我们首先使用 swagger-node-express 包自动生成文档。但是，我们意识到将 swagger 文档与 express 库分离对于使我们能够使用 Express 的所有特性和功能非常重要。我建议手动编写文档以完全控制您的应用程序将使用的 Swagger 文档和 Express Web 框架。
回答by mpashkovskiy
There is an option: you can embed middleware that will analyse all requests and responses and generate specification for you: https://github.com/mpashkovskiy/express-oas-generator
有一个选项：您可以嵌入中间件来分析所有请求和响应并为您生成规范：https: //github.com/mpashkovskiy/express-oas-generator
Then you can use it through your's app Swagger UI like http://host:port/api-docs
然后你可以通过你的应用程序 Swagger UI 使用它，比如http://host:port/api-docs
回答by Dariusz Filipiak
Yes !!!. You can use this awesome project typescript-test. Here is sample app. Clone it, run npm i,npm run swaggerand go to /dist/swagger.json. Done. Swagger yaml and json is generated based on express routes !
是的 ！！！. 你可以使用这个很棒的项目typescript-test。这是示例应用程序。克隆它，运行npm i，npm run swagger然后转到/dist/swagger.json。完毕。Swagger yaml 和 json 是基于快速路由生成的！
回答by ovidiu-miu
Have a look to swagger-jsdoc. It's a different approach.
看看swagger-jsdoc。这是一种不同的方法。
The docs stick to the code, and also lets the express code to remain pure.
文档坚持代码，也让表达代码保持纯净。
Guides:
指南：
