根据Swagger OpenAPI规范生成TypeScript类型

大家好，我是幻影，一名致力于编程知识传授的博主。今天我们要深入探讨一个非常有意思的话题——根据 Swagger OpenAPI 规范生成 TypeScript 类型。

你是不是也曾为手动创建 API 请求和响应的类型定义而头疼过？你是不是也想过，能不能通过一些工具自动化生成这些类型，从而减少重复劳动，避免出错？

好消息，今天我们就来深入解析如何利用 Swagger OpenAPI 规范与 TypeScript 配合，通过自动化工具生成类型，提升代码的可靠性和可维护性。

通过这篇教程，你将掌握如何根据 API 文档（Swagger）生成类型，并将这些类型与 TypeScript 的类型系统无缝结合。

一、什么是 Swagger OpenAPI 规范？

首先，我们要理解 Swagger 和 OpenAPI 规范的基本概念，因为它们是我们生成 TypeScript 类型的核心。

1. Swagger/OpenAPI 规范简介

Swagger 是一个开源框架，它帮助开发者设计、构建、文档化和使用 RESTful APIs。随着 OpenAPI 规范（OAS）的发布，Swagger 成为了这个规范的实施工具之一。OpenAPI 规范通过一个 JSON 或 YAML 文件来描述一个 API 的详细信息，包括请求方式（GET、POST 等）、路径、参数、响应类型等。

OpenAPI 规范的核心目的是通过机器可读的格式，使得开发者可以自动化地生成文档、客户端代码和服务器端代码。它不再局限于静态的文档展示，而是一个真正的交互式 API 规范。

举个例子，假如你有一个如下的 API 文档（Swagger 格式）：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Returns a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

这个文档描述了一个简单的 API /users，它是一个 GET 请求，返回一个包含用户信息的 JSON 数组。

二、TypeScript 与 OpenAPI 的结合：自动生成类型

通过将 OpenAPI 规范与 TypeScript 结合，开发者可以从 API 文档自动生成接口定义、请求参数、响应类型等，从而使 API 的使用更简单、规范，并且减少了手动编写类型的工作量。你不再需要每次修改 API 时手动更新 TypeScript 类型，所有的类型和文档都可以同步更新。

1. 需要的工具

我们需要以下工具来实现 OpenAPI 到 TypeScript 类型的生成：

Swagger Codegen 或 OpenAPI Generator：这些工具可以根据 OpenAPI 规范生成各种语言的客户端代码和类型定义。
TypeScript 相关工具：我们需要一些工具来生成 TypeScript 类型，并且集成到项目中。

2. 安装 OpenAPI Generator

首先，安装 OpenAPI Generator。这个工具可以从 OpenAPI 规范自动生成代码和类型。

你可以通过 npm 或 yarn 安装它：npm install @openapitools/openapi-generator-cli -g

或者通过 Homebrew 安装：brew install openapi-generator

3. 生成 TypeScript 类型

接下来，我们使用 openapi-generator 从 Swagger/OpenAPI 规范生成 TypeScript 类型。假设我们已经有一个 swagger.yaml 文件，表示了 API 的定义。我们可以运行以下命令来生成 TypeScript 类型：

openapi-generator-cli generate -i swagger.yaml -g typescript-fetch -o ./generated

解释一下这个命令：

-i swagger.yaml：指定输入的 OpenAPI 规范文件（swagger.yaml）。
-g typescript-fetch：指定生成的代码类型为 typescript-fetch，这是一个用于生成 TypeScript 客户端代码的模板。
-o ./generated：指定输出目录，生成的代码将存放在 ./generated 目录下。

执行这个命令后，./generated 文件夹下会生成 TypeScript 类型定义文件、API 客户端代码、请求方法等。我们可以直接在 TypeScript 项目中使用这些文件。

三、理解生成的 TypeScript 类型

在生成 TypeScript 类型后，你会看到类似这样的代码结构：

1. API 客户端代码

在 generated 文件夹中，生成的 ApiClient.ts 会包含所有的请求方法，例如：

export class UsersApi {
  private apiClient: ApiClient;

  constructor(apiClient: ApiClient) {
    this.apiClient = apiClient;
  }

  public async getUsers(): Promise<User[]> {
    const response = await this.apiClient.get('/users');
    return response.data;
  }
}

在这个例子中，我们看到 UsersApi 类的 getUsers 方法，它调用了 apiClient.get('/users') 来发起 GET 请求。apiClient 是一个自动生成的 API 客户端类，它会处理 HTTP 请求和响应。

2. TypeScript 类型

生成的 TypeScript 类型也会包括请求和响应的定义：

export type User = {
  id: number;
  name: string;
};

export type ApiResponse<T> = {
  data: T;
  status: number;
  message: string;
};

这些类型使得我们可以更精确地管理 API 请求和响应的数据结构，并且通过 TypeScript 的类型检查，确保我们的 API 调用和数据处理更加可靠。

四、集成到 Vue 项目中

现在，我们已经生成了 API 客户端和相关类型，接下来将其集成到一个 Vue 3 + TypeScript 项目中。假设我们在 Vue 3 项目中需要获取用户列表并展示。

1. 安装依赖

首先，确保你已经安装了 axios 或 fetch 作为 HTTP 请求库。你可以选择使用 axios，因为它更灵活且易于使用。npm install axios

2. 使用生成的 API 客户端

然后，在 Vue 组件中，导入生成的 API 客户端，并使用它来调用 API。

<template>
  <div>
    <h1>Users List</h1>
    <ul>
      <li v-for="user in users" :key="user.id">{{ user.name }}</li>
    </ul>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref, onMounted } from 'vue';
import { UsersApi } from './generated/ApiClient';
import { User } from './generated/Types';

export default defineComponent({
  name: 'UsersList',
  setup() {
    const users = ref<User[]>([]);

    const usersApi = new UsersApi(new ApiClient());

    const fetchUsers = async () => {
      try {
        const userList = await usersApi.getUsers();
        users.value = userList;
      } catch (error) {
        console.error('Error fetching users:', error);
      }
    };

    onMounted(() => {
      fetchUsers();
    });

    return {
      users
    };
  }
});
</script>