TypeScript 从 TypeScript 接口生成 Swagger 文档

在本文中，我们将介绍如何使用 TypeScript 生成 Swagger 文档。Swagger 是一个开源的 API 规范工具，它可以帮助开发者定义、构建、文档化和使用 RESTful Web 服务。

什么是 Swagger？

Swagger 是一个简化 RESTful Web 服务开发的工具集合。它提供了一种标准的方式来定义 API 的输入和输出，以及 API 的其他信息，如路径、参数、返回类型等。利用 Swagger，开发者可以根据 API 规范自动生成 API 文档、客户端和服务端代码。

Swagger 规范使用 YAML 或 JSON 格式来定义 API 的接口信息。通过使用 Swagger UI，开发者可以以可视化的形式查看并测试 API 的各种功能。

TypeScript 接口和 Swagger 文档

在 TypeScript 中定义接口是一种常用的方式，用于描述数据的结构和类型。TypeScript 接口是一种抽象的数据类型，它定义了一个对象的属性名称、类型和方法。我们可以利用 TypeScript 接口的这些特性来生成 Swagger 文档。

interface User {
  id: number;
  name: string;
  email: string;
}

interface Book {
  id: number;
  title: string;
  author: string;
}

上述代码定义了两个简单的 TypeScript 接口，分别是 User 和 Book。接下来我们将展示如何使用这些接口生成对应的 Swagger 文档。

使用 TypeDoc 生成 Swagger 文档

TypeDoc 是一个强大的文档生成器，可以从 TypeScript 代码生成文档。它支持将 TypeScript 接口转换为 Swagger 规范。

首先，我们需要安装 TypeDoc：

npm install -g typedoc

接下来，我们需要使用如下命令来生成 Swagger 文档：

typedoc --json swagger.json

上述命令将生成一个名为 swagger.json 的文件，其中包含了 TypeScript 接口的 Swagger 规范。

使用 swagger-jsdoc 生成 Swagger 文档

swagger-jsdoc 是一个将 JSDoc 注释转换为 Swagger 规范的工具。虽然它主要用于从 JavaScript 文件生成 Swagger 文档，但我们也可以通过在 TypeScript 接口中添加 JSDoc 注释来生成 Swagger 文档。

首先，我们需要安装 swagger-jsdoc：

npm install swagger-jsdoc

接下来，我们需要在 TypeScript 接口中添加 JSDoc 注释：

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: number
 *         name:
 *           type: string
 *         email:
 *           type: string
 */

interface User {
  id: number;
  name: string;
  email: string;
}

在上述示例中，我们使用了 @swagger 注释来定义 Swagger 规范中的组件。其中，User 是一个对象类型，包含了 id、name 和 email 三个属性。

接下来，我们需要使用 swagger-jsdoc 将 JSDoc 注释转换为 Swagger 规范。可以使用以下代码来实现：

import swaggerJSDoc from 'swagger-jsdoc';

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['*.ts'],
};

const swaggerSpec = swaggerJSDoc(options);

上述代码定义了 Swagger 文档的一些基本信息，并指定了解析 JSDoc 注释的文件路径。通过运行上述代码，我们将获取到包含了 TypeScript 接口定义的 Swagger 规范。

使用其他工具生成 Swagger 文档

除了 TypeDoc 和 swagger-jsdoc，还有许多其他工具可以用于从 TypeScript 生成 Swagger 文档。一些知名的工具包括 ts-swagger-gen、dts2swagger、ts-to-swagger 等。它们的使用方式和上述工具类似，都需要遵循特定的配置和规范。