我有自动生成Swagger json和手动编写它用于我帮助构建的API的经验。以下是根据我的经验得出的两者的优缺点。

Swagger自动生成文档：

我们将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 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库分离对于使我们能够使用Express的所有特性和功能非常重要。我建议您手动编写文档，以便完全控制Swagger文档和您的应用将使用的Express Web框架。

有一个选择：您可以嵌入中间件，它将分析所有请求和响应并为您生成规范：https://github.com/mpashkovskiy/express-oas-generator
然后，您可以通过您的应用程序Swagger UI使用它，如

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

使用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请求，而是检查express app示例和挂载的路由。

PRO您不需要执行提前请求来获取可用路由的更新列表。
CONs提供无类型参数特性。

看看swagger-jsdoc。这是一种不同的方法。
文档坚持代码，也让表达代码保持纯粹。
指南：

• https://dev.to/acanimal/express-api-with-autogenerated-openapi-doc-through-swagger-7na
• https://dev.to/akshendra/generating-documentation-on-the-fly-in-express-2652

您可以使用swagger-autogen，这是一个允许您使用注解自定义类型的工具。缺点是您必须花费时间来学习如何添加文档。