我继承了现有的API，我想用swagger记录它，但我还不知道它的全部范围 . Swagger（或其他中间件/工具）可以根据现有的快速路线自动神奇地生成yaml（用于招摇）吗？
对于我在其他问题上看到的情况，似乎这主要是一个手工工作，但我仔细检查是否有人在这里找到了办法 .
我有两个自动生成Swagger json的经验，并手动将其写出来用于我帮助构建的API . 根据我的经验，以下是两者的优缺点 .
我们将swagger-node-express模块与swagger-ui结合使用 . https://www.npmjs.com/package/swagger-node-expresshttps://github.com/swagger-api/swagger-ui
Pros
超级容易记录 . 只需在资源定义上方几行，文档（json）就会自动生成 .
Cons
使用此软件包时，您不再使用直接Express . 您的路线定义必须通过Swagger模块定义，这将使您远离vanilla Express .
我们只是将swagger-ui拉入项目并手动编写文档 .https://github.com/swagger-api/swagger-ui
这种方法将文档与Express框架分离 . Express endpoints 是按照通常编写的方式编写的，Swagger文档是与Express框架分开定义的 . 允许你写纯表达 .
由于您自己手动编写和更改yaml或json，因此文档更改变得更加乏味 . 这比仅更新资源上面的几行代码要困难一些 . 这种方法也更容易出现文档拼写错误和错误，因为它完全是手动输入的 .
如果您打算手动编写swagger文档，请使用下面的swagger编辑器验证您的手册文档 .http://editor.swagger.io/#/
对于这个API项目，我们首先使用swagger-node-express软件包自动生成文档 . 但是，我们意识到将swagger文档与快速库分离对于使我们能够使用Express的所有特性和功能非常重要 . 我建议手动编写文档以完全控制Swagger文档和应用程序将使用的Express Web框架 .
Yes !!! . 你可以使用这个很棒的项目typescript-test . 这是sample app . 克隆它，运行 npm i ， npm run swagger 并转到/dist/swagger.json . 完成 . Swagger yaml和json是基于快速路线生成的！
npm i
npm run swagger
有一个选项：您可以嵌入中间件来分析所有请求和响应并为您生成规范：https://github.com/mpashkovskiy/express-oas-generator
然后你可以通过你的应用程序Swagger UI使用它，如http://host:port/api-docs
3 回答
我有两个自动生成Swagger json的经验，并手动将其写出来用于我帮助构建的API . 根据我的经验，以下是两者的优缺点 .
Swagger AUTOMATIC文档生成：
我们将swagger-node-express模块与swagger-ui结合使用 . https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
超级容易记录 . 只需在资源定义上方几行，文档（json）就会自动生成 .
Cons
使用此软件包时，您不再使用直接Express . 您的路线定义必须通过Swagger模块定义，这将使您远离vanilla Express .
Swagger手册文档生成：
我们只是将swagger-ui拉入项目并手动编写文档 .
https://github.com/swagger-api/swagger-ui
Pros
这种方法将文档与Express框架分离 . Express endpoints 是按照通常编写的方式编写的，Swagger文档是与Express框架分开定义的 . 允许你写纯表达 .
Cons
由于您自己手动编写和更改yaml或json，因此文档更改变得更加乏味 . 这比仅更新资源上面的几行代码要困难一些 . 这种方法也更容易出现文档拼写错误和错误，因为它完全是手动输入的 .
如果您打算手动编写swagger文档，请使用下面的swagger编辑器验证您的手册文档 .
http://editor.swagger.io/#/
结论
对于这个API项目，我们首先使用swagger-node-express软件包自动生成文档 . 但是，我们意识到将swagger文档与快速库分离对于使我们能够使用Express的所有特性和功能非常重要 . 我建议手动编写文档以完全控制Swagger文档和应用程序将使用的Express Web框架 .
Yes !!! . 你可以使用这个很棒的项目typescript-test . 这是sample app . 克隆它，运行
npm i，npm run swagger并转到/dist/swagger.json . 完成 . Swagger yaml和json是基于快速路线生成的！有一个选项：您可以嵌入中间件来分析所有请求和响应并为您生成规范：https://github.com/mpashkovskiy/express-oas-generator
然后你可以通过你的应用程序Swagger UI使用它，如http://host:port/api-docs