借助 AI 将 Swagger 文档自动生成 TypeScript 类型与请求函数

后端接口一旦增加或调整，前端往往需要同步维护参数类型、响应结构和请求函数。接口数量较少时手写尚可接受，规模扩大后，重复编码和契约偏差就会持续消耗联调时间。借助 Swagger 提供的结构化定义，可以让 AI 按项目规范生成 TypeScript 接口层，并把人工工作集中到检查与必要的微调上。

每次后端给新接口，前端要做三件事：定义 TS 类型、写请求函数、写 mock 数据。一个接口 15 分钟，10 个接口就是半天。

我搭了一个工作流：后端 Swagger JSON → AI 转换 → 直接生成可用的 service 文件。接口层从"手工活"变成"自动化"。

以前的工作流

后端出接口文档（Swagger/飞书文档/口头描述）
           ↓
前端手写 TypeScript 类型       ← 15min/接口
           ↓
前端写请求函数                 ← 5min/接口
           ↓
发现类型和实际返回不一致       ← 联调时才知道
           ↓
改类型                         ← 5min/接口
           ↓
总计：25min/接口 × 10 = 4h

现在的工作流

后端出 Swagger 文档
           ↓
复制 JSON 给 AI（或直接引用 swagger.json）
           ↓
AI 生成 types + service 文件    ← 2min/10 个接口
           ↓
检查 + 微调                     ← 10min
           ↓
总计：12min（vs 之前 4h）

Prompt 模板

请根据以下 Swagger/OpenAPI 接口定义，生成 TypeScript 代码：

## 生成要求
1. **类型定义**：Request 和 Response 的 interface
2. **请求函数**：使用 `request` 实例（import from '@/api/axios'）
3. **命名规范**：
   - 类型名：大驼峰，以 Params/Response 结尾
   - 函数名：小驼峰，以 HTTP 方法开头（get/post/put/delete）
4. **注释**：每个接口函数加中文注释说明用途
5. **导出**：全部 named export

## 项目约定
- 请求实例：import request from '@/api/axios'
- 响应包装：接口返回 { code: number, data: T, msg: string }，只需要定义 data 的类型
- 日期字段：string 类型（后端返回字符串）
- 分页参数：{ pageNum: number, pageSize: number }
- 分页响应：{ list: T[], total: number }

## Swagger JSON
[粘贴接口定义]

实际生成效果

输入（Swagger 片段）：

{
  "/api/store/list": {
    "get": {
      "summary": "门店列表",
      "parameters": [
        { "name": "storeName", "in": "query", "type": "string" },
        { "name": "status", "in": "query", "type": "integer", "enum": [0, 1, 2] },
        { "name": "pageNum", "in": "query", "type": "integer" },
        { "name": "pageSize", "in": "query", "type": "integer" }
      ],
      "responses": {
        "200": {
          "schema": {
            "properties": {
              "list": {
                "type": "array",
                "items": {
                  "properties": {
                    "storeId": { "type": "integer" },
                    "storeName": { "type": "string" },
                    "status": { "type": "integer" },
                    "address": { "type": "string" },
                    "createTime": { "type": "string" }
                  }
                }
              },
              "total": { "type": "integer" }
            }
          }
        }
      }
    }
  }
}

AI 输出：

import request from '@/api/axios'

/** 门店状态枚举 */
export enum StoreStatus {
  /** 未启用 */
  Disabled = 0,
  /** 已启用 */
  Enabled = 1,
  /** 已关闭 */
  Closed = 2,
}

/** 门店列表查询参数 */
export interface GetStoreListParams {
  storeName?: string
  status?: StoreStatus
  pageNum: number
  pageSize: number
}

/** 门店信息 */
export interface StoreItem {
  storeId: number
  storeName: string
  status: StoreStatus
  address: string
  createTime: string
}

/** 门店列表响应 */
export interface GetStoreListResponse {
  list: StoreItem[]
  total: number
}

/** 查询门店列表 */
export const getStoreList = (params: GetStoreListParams) =>
  request.get<GetStoreListResponse>('/api/store/list', { params })

处理复杂场景

嵌套对象

{
  "orderInfo": {
    "orderId": "string",
    "items": [{ "goodsId": "number", "goodsName": "string", "specs": [{"specId": "number"}] }]
  }
}

AI 会自动拆分为多个 interface：

export interface OrderSpec {
  specId: number
}

export interface OrderItem {
  goodsId: number
  goodsName: string
  specs: OrderSpec[]
}

export interface OrderInfo {
  orderId: string
  items: OrderItem[]
}

可选字段推断

AI 根据 Swagger 的 required 字段自动标记可选：

export interface UpdateStoreParams {
  storeId: number        // required
  storeName?: string     // optional
  address?: string       // optional
}

enum 转 TypeScript 枚举

当 Swagger 标注了 enum + description，AI 会生成带注释的枚举。

增量更新策略

后端改了接口怎么办？

方案 1（简单粗暴）：
├── 把新 Swagger 丢给 AI
├── AI 重新生成整个文件
└── 用 diff 工具对比变化

方案 2（精准更新）：
├── 只把改动的接口丢给 AI
├── "帮我更新 getStoreList 的响应类型，新增了 phone 字段"
└── AI 只修改对应的 interface

我们用方案 2，因为方案 1 可能覆盖掉自己手动调整过的部分。

和 Steering 配合

在 steering 里声明项目的接口规范，AI 生成时自动遵守：

## 接口层规范
- 文件位置：src/services/{domain}/{feature}.ts
- 请求实例：import request from '@/api/axios'
- GET 请求参数放 params，POST 放 data
- 响应类型泛型：request.get<ResponseType>(url, { params })
- 文件上传用 FormData + multipart/form-data header
- 枚举值用 enum，不用 union type

投入产出

一次性投入：
├── 写 Prompt 模板：30min
├── 配置 steering 约定：20min
└── 总计：50min

每次使用节省：
├── 10 个接口：从 4h → 12min
├── 按每周新增 5-8 个接口算
├── 每周节省：~2h
├── 每月节省：~8h
└── 3 个月：~24h（3 个工作日）

---

? 你们前端的接口类型是手写的还是自动生成的？有用过 swagger-typescript-api 之类的工具吗？

---

? 完整 Skills 源码已开源：github.com/sleepyccat/…，欢迎 Star ⭐ 和 PR。