Question

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

就我在其他问题上所看到的情况而言，这似乎主要是手工作业，但我会仔细检查是否有人在这里找到了解决方法。

Answer 1

我有两种自动生成Swagger json的经验，并手动将其写出来为我帮助构建的API。根据我的经验，以下是两者的优缺点。

Swagger AUTOMATIC文档生成：

<强>赞成

超级易于记录。只需在资源定义上方抛出几行，文档（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框架。

Answer 2

是!!! 。您可以使用这个很棒的项目typescript-test。这是sample app。克隆它，运行npm i，npm run swagger并转到 /dist/swagger.json 。完成。 Swagger yaml和json是基于快速路线生成的！

Answer 3

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

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

Answer 4

看看swagger-jsdoc。这是另一种方法。

文档坚持使用代码，还使表达的代码保持纯净。

指南：

Answer 5

使用 express-sitemap-html，您可以自动生成简约的 Open API 定义（仅包括路由参数）并为现有 Express 应用的所有路由安装 Swagger UI。你只需要：

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Your app name', app) // given that app is an express instance

这种方法不是在运行时分析 HTTP 请求，而是检查快速 app 实例和已安装的路由。

PROs 您无需执行提前请求即可获取可用路线的更新列表。

CONs 它提供了无类型参数功能。