快速开始

本指南将帮你快速上手 OpenAPI Generator 和相关工具，在 10 分钟内完成从 OpenAPI 规范到客户端代码和文档的完整流程。

🎯 学习目标

• 安装必要的工具
• 从 OpenAPI 规范生成客户端代码
• 生成漂亮的 API 文档
• 了解基本的工作流程

📋 准备工作

系统要求

• Node.js 16+
• npm 或 yarn
• Git (可选)

检查环境

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

版本建议

推荐使用 Node.js 18+ 以获得最佳性能和兼容性。

🔧 安装工具

安装 OpenAPI Generator CLI

# 全局安装 (推荐)
npm install @openapitools/openapi-generator-cli -g

# 或使用 npx (无需安装)
npx @openapitools/openapi-generator-cli version

安装 Redocly CLI

# 全局安装
npm install @redocly/cli -g

# 检查安装
npx @redocly/cli --version

🚀 第一个示例

1. 准备 OpenAPI 文件

创建一个简单的 OpenAPI 规范文件 api.yaml：

openapi: 3.0.1
info:
  title: Hello API
  description: 我的第一个 API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /hello:
    get:
      summary: 问候接口
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hello, World!"

2. 生成 TypeScript 客户端

# 生成 TypeScript 客户端
npx @openapitools/openapi-generator-cli generate \
  -i api.yaml \
  -g typescript-fetch \
  -o client/typescript

3. 生成 API 文档

# 生成 HTML 文档
npx @redocly/cli build-docs api.yaml -o docs.html

# 启动预览服务器
npx @redocly/cli preview-docs api.yaml

📊 结果展示

完成上述步骤后，你将得到：

生成的客户端代码

// client/typescript/apis/DefaultApi.ts
export class DefaultApi {
  public async hello(): Promise<{ message: string }> {
    // 自动生成的客户端代码
  }
}

生成的文档

<!-- docs.html - 包含完整的交互式 API 文档 -->

🎯 下一步

恭喜！你已经完成了基础流程。接下来可以：

• 了解更多生成器选项
• 学习文件合并技巧
• 探索高级文档主题
• 配置自动化流程

❓ 遇到问题？

如果遇到问题，可以查看：

• 常见问题
• 故障排除
• GitHub Issues

注意

确保你的 OpenAPI 规范文件语法正确。可以使用以下命令验证：

npx @redocly/cli lint api.yaml