【亲测免费】 OpenAPI Typescript 项目教程

1. 项目介绍

openapi-ts 是一个开源项目，旨在将 OpenAPI 规范转换为美观的 TypeScript 客户端。该项目支持 OpenAPI 2.0、3.0 和 3.1 规范，并且支持 JSON 和 YAML 格式的输入文件。生成的 TypeScript 客户端包括接口、REST 客户端和 JSON 模式。

主要功能

• 支持 OpenAPI 2.0、3.0 和 3.1 规范
• 支持 JSON 和 YAML 格式的输入文件
• 生成 TypeScript 接口、REST 客户端和 JSON 模式
• 支持多种客户端：Fetch API、Axios、Angular、Node.js 和 XHR

2. 项目快速启动

安装

首先，确保你已经安装了 Node.js 18+。然后，你可以通过以下命令安装 openapi-ts：

npm install @hey-api/openapi-ts

使用示例

假设你有一个 OpenAPI 规范文件 openapi.yaml，你可以使用以下命令生成 TypeScript 客户端：

npx openapi-ts generate -i openapi.yaml -o ./generated

生成的文件将位于 ./generated 目录中。

代码示例

以下是一个简单的使用示例，展示如何使用生成的 TypeScript 客户端：

import { ApiClient } from './generated/api-client';

const client = new ApiClient({
  baseUrl: 'https://api.example.com',
});

async function fetchData() {
  const response = await client.get('/users');
  console.log(response.data);
}

fetchData();

3. 应用案例和最佳实践

应用案例

openapi-ts 可以广泛应用于需要与 RESTful API 交互的前端和后端项目中。例如：

• 前端开发：在 React 或 Angular 项目中，使用生成的 TypeScript 客户端与后端 API 进行交互。
• 后端开发：在 Node.js 项目中，使用生成的 TypeScript 客户端与第三方 API 进行交互。

最佳实践

• 版本控制：确保你的 OpenAPI 规范文件和生成的 TypeScript 客户端都纳入版本控制。
• 自动化：将 openapi-ts 集成到你的 CI/CD 流程中，以便在 API 规范更新时自动生成客户端代码。
• 文档化：为生成的 TypeScript 客户端编写详细的文档，帮助团队成员快速上手。

4. 典型生态项目

相关项目

• Swagger UI：用于可视化 OpenAPI 规范的工具。
• OpenAPI Generator：一个更通用的 OpenAPI 代码生成器，支持多种语言和框架。
• Redoc：另一个用于可视化 OpenAPI 规范的工具，提供更现代的 UI。

集成

你可以将 openapi-ts 与其他工具集成，例如：

• Swagger UI：在生成 TypeScript 客户端后，使用 Swagger UI 可视化 API 文档。
• OpenAPI Generator：结合使用 openapi-ts 和 OpenAPI Generator，生成更全面的客户端代码。

通过这些集成，你可以构建一个完整的 API 开发和文档生态系统。