Swagger可以根据现有的快递路线自动生成yaml吗?

我inheritance了一个现有的API,并且想用swagger来logging它,但我还不知道它的全部范围。 Swagger(或其他中间件/工具)是否可以根据现有的快速路线自动奇迹般地产生yaml(对于swagger)?

对于我在其他问题上看到的情况,看起来这主要是一项手工工作,但是我仔细检查这里是否有人find解决办法。

       

网上收集的解决方案 "Swagger可以根据现有的快递路线自动生成yaml吗?"

我有在自动生成Swagger json和手动写出我帮助build立的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模块进行定义,这使您远离了vanilla Express。

Swagger手册文档生成:

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

优点

这种方法将文档从Express框架中分离出来。 Express端点是按照通常写入的方式编写的,Swagger文档是与Express框架分开定义的。 允许你写纯粹的快递。

缺点

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

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

结论

对于这个API项目,我们首先使用swagger-node-express包自动生成文档。 但是,我们意识到将swagger文档从快速库中解耦出来对于使我们能够使用Express的所有function和特性非常重要。 我build议手动编写文档,以便完全控制您的应用将使用的Swagger文档和Express Web框架。

是的! 。 你可以使用这个令人敬畏的项目打字稿testing 。 这里是示例应用程序 。 克隆它,运行npm inpm run swagger并转到/dist/swagger.json 。 完成。 Swagger yaml和json是基于快速路线生成的!