Swagger可以根据现有的快速路线自动生成其yaml吗？

Question

我继承了现有的API,我想用swagger记录它,但我还不知道它的全部范围.Swagger(或其他中间件/工具)可以根据现有的快速路线自动神奇地生成yaml(swagger)吗？

对于我在其他问题上看到的情况,似乎这主要是一个手工工作,但我仔细检查是否有人在这里找到了办法.

Answer 1

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

Swagger AUTOMATIC文档生成:

优点

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

缺点

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

我们只是将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框架.

谢谢Mike,我理解这些方法,但我不认为第一个真的是"自动魔术",因为我仍然需要定义大部分情况.我正在寻找一些基本上可以解释路由并生成类似手册文档的东西,我可以填写它无法从代码本身解释的空白. (3认同)
已经过两天的搜索,但我还没有找到端到端的工作解决方案.http://www.npmjs.com/package/expressjs-api-explorer看起来很有前途,但是马车不适合我.想法是使用API-Explorer库生成输出并转换为swagger期望的YAML,然后使用Mike建议的许多库中的一个使用静态YAML文件. (2认同)
@Mike-手动方法的问题是您正在将文档从代码中移开。以我的经验，这几乎不可避免地导致文档过时（这比没有文档更糟糕），因为现在您必须将文档保存在单独的位置。使文档保持最新状态的最佳方法是使其尽可能接近代码。归根结底，代码将生存下去，因此，如果将任何重要工件都拴在代码上，那么我们必须保留的重要工件才有生存的最佳机会。 (2认同)

Answer 2

有一个选项：您可以嵌入中间件来分析所有请求和响应并为您生成规范：https : //github.com/mpashkovskiy/express-oas-generator

然后你可以通过你的应用程序 Swagger UI 使用它，比如http://host:port/api-docs