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

Question

我继承了一个现有的 API，我想 Swagger 记录它，但我还不知道它的全部范围。 Swagger(或其他中间件/工具)能否根据现有的快速路由自动生成 yaml(用于 swagger)？

对于我在其他问题上看到的情况，这似乎主要是一项手动工作，但我正在仔细检查这里是否有人找到解决此问题的方法。

Answer 1

我在自动生成 Swagger json 和为我帮助构建的 API 手动编写它方面都有经验。根据我的经验，这是两者的优缺点。

Swagger 自动文档生成:

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

优点

super 容易记录。只需在资源定义上方添加几行代码，模块就会自动生成文档(json)。

缺点

当您使用此软件包时，您不再直接使用 Express。您的路线定义必须通过 Swagger 模块定义，这会让您远离 vanilla Express。

Swagger 手册文档生成:

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

优点

这种方法将文档与 Express 框架分离。 Express 端点的编写方式与它们通常的编写方式相同，并且 Swagger 文档的定义与 Express 框架分开。让你写纯 express 。

缺点

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

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

结论

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