使用hey-api/openapi-ts快速生成TypeScript API客户端指南

项目概述

hey-api/openapi-ts是一个强大的OpenAPI到TypeScript代码生成工具，每月被调用超过200万次，用于生成可靠的API客户端和SDK。该项目采用MIT许可证，完全免费使用。

核心特性

1. 多环境支持：

   • 可在CLI、Node.js 18+或npx环境中运行
   • 支持Next.js、Nuxt等现代前端框架

2. 规范兼容性：

   • 全面支持OpenAPI 2.0、3.0和3.1规范
   • 可生成自定义类型和SDK

3. 扩展能力：

   • 提供插件生态系统减少样板代码
   • 支持开发自定义插件和客户端
   • 与Hey API平台无缝集成

快速入门

通过npx快速体验

最简单的方式是使用npx直接运行：

npx @hey-api/openapi-ts \
  -i https://get.heyapi.dev/hey-api/backend \
  -o src/client

执行后将在src/client目录下生成完整的API客户端代码。

项目安装方式

根据你的包管理器选择适合的安装命令：

# npm
npm install @hey-api/openapi-ts -D

# pnpm
pnpm add @hey-api/openapi-ts -D

# yarn
yarn add @hey-api/openapi-ts -D

# bun
bun add @hey-api/openapi-ts -D

建议固定具体版本号以确保稳定性，因为在v1版本发布前API可能会有变化。

使用方式

CLI方式

推荐在package.json中添加脚本：

"scripts": {
  "openapi-ts": "openapi-ts"
}

然后通过npm run openapi-ts命令执行。

Node.js编程方式

也可以在TypeScript文件中编程调用：

import { createClient } from '@hey-api/openapi-ts';

createClient({
  input: 'https://get.heyapi.dev/hey-api/backend',
  output: 'src/client',
});

最佳实践

1. 配置管理：建议将配置提取到单独的文件中管理
2. 版本控制：在项目早期阶段，注意API可能的变化
3. 输出定制：可以根据需要定制生成的类型和SDK

注意事项

目前该项目仍处于初期开发阶段，接口可能会在稳定版发布前发生变化。建议开发者关注项目动态，及时获取最新信息。

通过本指南，开发者可以快速上手使用hey-api/openapi-ts工具，为项目生成类型安全的API客户端代码，提高开发效率和代码质量。