如何从基于 TypeScript 的 Express 应用程序生成 swagger API 文档？

Posted 2023-03-13

【中文标题】如何从基于 TypeScript 的 Express 应用程序生成 swagger API 文档？

【英文标题】：How to generate swagger API doc from TypeScript based Express app?

【发布时间】：2019-12-19 23:54:03

【问题描述】：

我可以使用 Express API with autogenerated OpenAPI doc through Swagger 文章配置 swagger url。

我正在使用 TypeScript，它在 dist 下生成 .js 文件，该文件没有添加任何 API doc cmets。指向 apis: ['../dist/*.js'] 或 Route.ts 会生成 API 详细信息。我没有使用任何休息装饰器。

/**
 * @swagger
 * /:
 *    get:
 *      description: This should return ok
 */
this.router.get("/", (req: Request, res: Response) => this.api.process(req, res));

Routes.ts API 文档如上所示。如何由此生成 swagger doc？

【问题讨论】：

使用 tsoa，将它们的装饰器添加到您的控制器类中，您可以自动化它。

【参考方案1】：

我建议您使用可以为您处理所有内容的库，例如 tsoa，它可以轻松地从您的 TypeScript 类型生成 Swagger/OpenAPI 文档。它还为您执行运行时验证，以便您知道请求实际上是 TypeScript 所说的类型。自述文件包含开始使用它所需的所有设置信息。它与 express、hapi、koa 等兼容：

https://github.com/lukeautry/tsoa

---

（完全透明：我是 tsoa 的维护者之一。但我最初是 tsoa 的消费者，我发现它是一个很棒的产品......这就是我要求帮助维护它的原因！:)）

【讨论】：

我手动为 API 编写 yml 文件，并使用 redoc 生成 html 文件。无法在有限的时间内使类型和注释正常工作。

hapi server也有同样的解决方案（不是express）？

tsoa 能否从纯 Typescript 生成 OpenAPI 文档，即只是一个接口或类？我浏览了文档，似乎需要一个 Node 应用程序才能生成 OpenAPI 文档