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 模块定义，这会让您远离 vanilla Express.

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屋！