Saylo - 全栈开发工程师

背景

在前后端分离的开发模式中，接口协议是前后端协作的纽带。传统的做法是前端手动编写接口类型定义，手动维护接口调用代码。这种方式容易出错、难以追踪变更、接口文档和代码容易脱节。

qxun-api-generator 正是为了解决这一痛点而生的。

核心功能

Swagger → TypeScript 类型

解析 OpenAPI 3.0 / Swagger 2.0 协议，自动生成完整的 TypeScript 类型定义，包括：

请求参数类型
响应数据类型
路径参数、Query 参数类型
Header 参数类型

TanStack Query 集成

生成的接口自动封装为 TanStack Query hooks，支持：

自动缓存和重新请求
请求重试机制
轮询和实时更新
乐观更新

错误码自动映射

支持配置业务错误码体系，生成统一的错误处理逻辑。

AI Agent 友好

生成的代码包含丰富的类型注解和 JSDoc 注释，AI Agent 可以准确理解每个接口的语义，实现智能化的接口调用和业务逻辑生成。

Swagger 自动生成接口原理

1. 数据源：OpenAPI 规范文档

后端提供标准 OpenAPI 3.0 JSON，包含：

接口路径
请求方式
请求 / 响应结构
字段类型

示例结构：

{
  "paths": {
    "/api/business/settings/hr/save": {
      "post": {
        "operationId": "saveHr",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BusinessSettingsHrSaveValidate" }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BusinessSettingsHrSaveValidate": {
        "properties": {
          "name": { "type": "string" },
          "avatar": { "type": "string" }
        }
      }
    }
  }
}

2. 生成器：openapi-generator

工具根据 JSON 自动生成：

api.ts：所有接口方法
types.ts：所有 TS 类型
配置、基础请求封装

自动映射规则：

OpenAPI 字段	生成 TypeScript 类型
type: string	string
type: integer	number
type: boolean	boolean
type: array	T[]
$ref: #/components/schemas/X	X
required: [...]	类型必需的字段

3. 生成后的三层结构

AxiosParamCreator
   ↓
DefaultApiFp
   ↓
DefaultApiFactory / DefaultApi

AxiosParamCreator：拼接 URL、header、body
DefaultApiFp：封装请求函数
DefaultApiFactory：最终调用，执行 axios 请求

4. 完整调用链

DefaultApiFactory().saveHr(params)
  ↓
DefaultApiFp().saveHr(params)
  ↓
AxiosParamCreator.saveHr(params) → 生成 request 参数
  ↓
createRequestFunction → 执行 axios.request

使用方式

环境安装

# 安装公司内部接口生成工具
npm i qxun-api-generator

# 未安装 openapi-generator 时执行
brew install openapi-generator

项目结构

src/
└── apis/            # 固定存放 api.json
    ├── api.json     # 生成配置文件
    └── consumer/    # 自动生成的接口模块目录

配置文件 api.json

{
    "$schema": "../../node_modules/qxun-api-generator/lib/schema.json",
    "apis": [{
        "service": "consumer",
        "outputDir": "./",
        "path": "https://test.business.yuugeai.com/v3/api-docs/business",
        "httpPath": "import { http as globalAxios } from '../../utils/http'",
        "baseUrl": ""
    }]
}

使用方式（极简）

无需手写接口地址、无需声明 TS 类型，一行调用。

import { useMutation } from '@tanstack/react-query';
import { DefaultApiFactory, BusinessSettingsHrSaveValidate } from '@/apis/consumer';

const { mutateAsync: saveHr } = useMutation({
    mutationFn: (params: BusinessSettingsHrSaveValidate) =>
        DefaultApiFactory().saveHr({ businessSettingsHrSaveValidate: params }),
});

总结

这套方案让前端：

✅ 不用写接口
✅ 不用写类型
✅ 不用管路径
✅ 不用处理异常重试
✅ 配合 React Query 开箱即用缓存、乐观更新

真正实现：接口自动化、类型安全化、开发高效化。

从零打造一个 Swagger → TypeScript 代码生成器

背景