Swagger是否可以基于现有的快递路线自动生成其Yaml? [英] Can Swagger autogenerate its yaml based on existing express routes?

问题描述

我继承了一个现有的API，我想大张旗鼓地记录下来，但是我还不知道它的全部范围. Swagger(或其他中间件/工具)是否可以根据现有的快速路线自动生成Yaml(用于swagger)?

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?

对于我在其他问题上看到的内容，看来这主要是一项手动工作，但我正在仔细检查这里是否有人找到解决方法.

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.

推荐答案

我在自动生成Swagger json并将其手动写入为我帮助构建的API方面都有经验.根据我的经验，这两者都是优点/缺点.

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-node-express模块​​与swagger-ui结合使用. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui

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

专业人士

超级容易记录.只需在资源定义上方添加几行，文档(json)就会由模块自动生成.

Super easy to document. Just throw a few lines above the resource definition and the documentation (json) is automatically generated by the module.

缺点

使用此程序包时，您不再使用Express.您的路线定义必须通过Swagger模块进行定义，这使您脱离了香草快车.

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.

我们刚刚将swagger-ui拖入了项目并手动编写了文档.
https://github.com/swagger-api/swagger-ui

We just pulled swagger-ui into the project and wrote the documentation manually.
https://github.com/swagger-api/swagger-ui

专业人士

这种方法使文档与Express框架脱钩. Express端点的编写与通常编写时相同，并且Swagger文档是与Express框架分开定义的.允许您编写纯快递.

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.

缺点

由于您自己手动编写和更改yaml或json，因此文档更改变得有些乏味.这比仅更新资源上方的几行代码要困难一点.由于这种方法完全是手动键入的，因此它也更容易出现文档输入错误和错误.

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.

如果您打算手动编写swagger文档，请使用下面的swagger编辑器来验证您的手动文档.
http://editor.swagger.io/#/

If you are planning to manually write your swagger documentation use the swagger editor below to validate your manual docs.
http://editor.swagger.io/#/

对于这个API项目，我们首先使用swagger-node-express包自动生成文档.但是，我们意识到将swagger文档与Express库分离非常重要，这使我们能够使用Express的所有功能.我建议手动编写文档，以完全控制您的应用程序将使用的Swagger文档和Express Web框架.

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.

这篇关于Swagger是否可以基于现有的快递路线自动生成其Yaml?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！