【学习资料】Next.js 使用 OpenAPI 的新玩法：openapi-typescript 与 openapi-fetch 初体验

在现代 API 驱动的开发中，OpenAPI 是一个十分流行的标准，它可以清晰定义 API 接口。而 openapi-typescript 和 openapi-fetch 这两个库让我们在 Next.js 项目中利用 OpenAPI 变得更加便捷和类型安全。今天我们就来快速上手这两位“新朋友”，带你感受轻松、高效的 API 开发体验！

神奇小广告

引言

在现代 API 驱动的开发中，OpenAPI 是一个十分流行的标准，它可以清晰定义 API 接口。而 openapi-typescript 和 openapi-fetch 这两个库让我们在 Next.js 项目中利用 OpenAPI 变得更加便捷和类型安全。今天我们就来快速上手这两位“新朋友”，带你感受轻松、高效的 API 开发体验！

1. 准备工作：安装依赖包

首先，安装 openapi-typescript 和 openapi-fetch，让我们为 Next.js 项目打下基础。

npm install openapi-typescript openapi-fetch

解释：openapi-typescript 用于根据 OpenAPI 文档生成 TypeScript 类型，而 openapi-fetch 提供了一个轻量的 fetch 实现，便于与类型结合使用。

2. 使用 openapi-typescript 生成 API 类型

我们先下载 OpenAPI 文档，或从 URL 获取 OpenAPI 的 JSON 文件。然后，用 openapi-typescript 生成类型定义文件。

代码示例：

npx openapi-typescript https://api.example.com/openapi.json --output src/types/api.d.ts

解释：上面的命令会生成一个 api.d.ts 文件，其中包含 OpenAPI 文档中定义的所有接口类型。这些类型将帮助我们在调用 API 时获得代码提示和类型检查。

3. 在项目中配置 openapi-fetch

接下来，让我们在 Next.js 项目中集成 openapi-fetch。我们先导入 createClient 并初始化一个 fetch 客户端。

代码示例：

import { createClient } from 'openapi-fetch';
import { paths } from '../types/api';

const client = createClient<paths>({
  baseUrl: 'https://api.example.com',
});

解释：这里我们将生成的 paths 类型传递给 createClient，这样 client 就会有类型提示和约束，帮助我们避免错误的请求。

4. 发起请求：类型安全的 API 调用

我们已经完成了设置，现在可以直接使用类型安全的 API 调用啦！比如我们要获取用户信息，只需按照 OpenAPI 文档定义的接口路径调用 client。

代码示例：

async function getUser() {
  const { data, error } = await client.get('/users/{userId}', {
    params: { userId: '123' },
  });

  if (error) {
    console.error('请求失败:', error);
    return;
  }

  console.log('用户数据:', data);
}

解释：上面我们使用 client.get 发起请求，传入 userId 参数。因为有了类型定义，IDE 会对传入参数进行检查并提供提示。如果请求出错，error 会帮助我们快速调试问题。

5. 处理 POST、PUT 等其他请求方法

除了 GET，openapi-fetch 还支持 POST、PUT、DELETE 等常见 HTTP 方法。例如，我们可以轻松添加一个新用户。

代码示例：

async function addUser() {
  const { data, error } = await client.post('/users', {
    body: {
      name: '新用户',
      email: '[email protected]',
    },
  });

  if (error) {
    console.error('添加用户失败:', error);
    return;
  }

  console.log('用户已添加:', data);
}

解释：这段代码展示了如何使用 POST 方法创建用户。只需传入 body 参数，类型检查会自动确保我们传入的数据符合 OpenAPI 文档的定义。