可以Swagger自动生成它是基于现有快递路线的yaml？ [英] Can Swagger autogenerate it's yaml based on existing express routes?

问题描述

我继承了一个现有的API，我想用swagger来记录它，但是我还不知道它的全部范围。可以Swagger（或另一个中间件/工具）根据现有的快递路线自动产生yaml（对于swagger）？

对于我在其他问题上看到的似乎这主要是一个手工的工作，但是我会仔细检查一下这里是否有人找到了解。

解决方案

我有BOTH自动生成Swagger json的经验，并手动编写一个我帮助构建的API。这是基于我的经验的利弊。

Swagger AUTOMATIC文档生成：

我们将swagger-node-express模块​​与swagger-ui 。
https://www.npmjs.com/package/swagger-node-express < br>
https://github.com/swagger-api/swagger-ui

优点

超级简单的文档。只需在资源定义之上抛出几行，并且模块自动生成文档（json）。

缺点

当您使用这个包。您的路线定义必须通过Swagger模块进行定义，这将使您远离vanilla 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框架。

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.

解决方案

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 AUTOMATIC Documentation Generation:

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

Pros

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

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.

Swagger MANUAL Documentation Generation:

We just pulled swagger-ui into the project and wrote the documentation manually.
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.

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.

If you are planning to manually write your swagger documentation use the swagger editor below to validate your manual docs.
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.

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