从 typescript 接口生成 swagger 文档答案

【问题标题】：Generating swagger docs from typescript interfaces从 typescript 接口生成 swagger 文档
【发布时间】：2019-05-03 09:08:13
【问题描述】：

我正在使用swager-jsdoc 记录应用程序的所有 DTO。

我想知道有什么方法可以从 typescript 接口自动生成 swagger 文档。

我在项目中有很多，还有很多猫鼬模式和模型。让它们保持同步变得越来越乏味。另一方面，我不想使用 swagger 生成工具。我更喜欢自下而上的方法。

干杯

【问题讨论】：

找到了一个相关问题，但针对generating mongoose schemas。用一颗子弹射两只兔子就好了。
找到typegoose。这解决了一半的问题：D 仍在寻找招摇的对手。

标签： typescript swagger openapi

【解决方案1】：

tsoa 的另一个选项是routing-controllers + routing-controllers-openapi。两者（AFAIK）之间的主要区别在于tsoa 依赖于代码生成，而routing-controllers 完全在运行时运行。这两种方法都有其优点：tsoa 能够例如利用更丰富的元数据（例如代码 cmets），而使用 routing-controllers 我们可以跳过生成步骤。我的建议是两个都去看看！

另一个选项是typescript-json-schema，它从 Typescript 接口生成 JSON Schema；在 JSON Schema 中定义模型后，您与 OpenAPI 规范相差不远。

【讨论】：

请注意，TSOA 当前不支持特定于路由的中间件。此外，routing-controllers-openapi 似乎不像 TSOA 那样功能丰富。

【解决方案2】：

是的，您可以使用 tsoa 从您的 TypeScript 类型轻松生成 Swagger 和 OpenAPI 文档。自述文件包含开始使用它所需的所有设置信息。它与 express、hapi、koa 等兼容：

https://github.com/lukeautry/tsoa

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

【讨论】：

为什么 tsoa 目前不支持特定于路由的中间件。还有这个特定功能的解决方法吗？
这是一个更适合作为 github 问题作为 tsoa 的功能请求的问题。但简短的回答是类型安全。在他们的 github 中询问 tsoa 的新维护者，您可能会得到不同的答案。

【解决方案3】：

另一个选项是使用 https://www.npmjs.com/package/ts-to-openapi 从接口生成 Swagger Schemas。

示例：考虑下面的用户界面：

export interface User {
  name: string;
  email: string;
  nickname?: string;
}

在终端运行以下命令：

npx ts-to-openapi -f User.ts -t User >> User.ts

在此之后，您的界面用户将更新如下：

export interface User {
  name: string;
  email: string;
  nickname?: string;
}

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       additionalProperties: false
 *       properties:
 *         email:
 *           type: string
 *         name:
 *           type: string
 *         nickname:
 *           type: string
 *       required:
 *         - name
 *         - email
 *       type: object
 */

【讨论】：

ts-to-openapi 包“不再大量维护”，项目页面指向更活跃、更全面的 typeconv 包，它支持的不仅仅是 ts/openAPI 生成