node.js – Swagger可以根据现有的快速路由自动生成其yaml吗？

我有两个自动生成Swagger json的经验,并手动将其写出来用于我帮助构建的API.根据我的经验,以下是两者的优缺点.

Swagger AUTOMATIC文档生成：

我们将swagger-node-express模块​​与swagger-ui结合使用.
https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui

优点

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

缺点

使用此软件包时,您不再使用直接Express.您的路线定义必须通过Swagger模块定义,这将使您远离香草Express.

Swagger MANUAL文档生成：

我们只是将swagger-ui拉入项目并手动编写文档.
https://github.com/swagger-api/swagger-ui

优点

这种方法将文档与Express框架分离. Express端点是按照通常编写的方式编写的,Swagger文档是与Express框架分开定义的.允许你写纯表达.

缺点

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

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

结论

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