“这个接口的入参是什么结构？”
“返回值里 list 的每个 item 有哪些字段？”
“这个接口是 GET 还是 POST？”

每次写新页面都要翻接口文档，找到对应接口，看参数结构，然后手写 TypeScript 类型定义。

200+ 个接口，每个都要重复这个过程。

后来我做了一件事：把接口信息"喂"给 AI，让它永远记住。

3 种做法（选适合你的）

🗺️ 整体方案流程图

为了让您更清晰地了解如何选择适合自己的方案，以下是三种方法的决策和执行流程图：

方式一：引用 Swagger 文档（最省事）

如果后端有 Swagger/OpenAPI，导出 JSON 放到项目里，然后在 AI 配置中引用：

# API 规范

接口定义见 #[[file:docs/api-spec.json]]

## 调用规范
- 接口函数放 src/services/<domain>/
- 命名：动词 + 资源名（getActivityList, createCoupon）
- 必须定义 Request/Response interface
- 统一使用 src/api/axios.ts 的实例

方式二：维护精简接口清单（最实用）

没有 Swagger？手动维护一份也行：

# 接口清单

## 营销域
- POST /api/activity/list — 活动列表（分页）
- POST /api/activity/create — 创建活动
- POST /api/activity/update — 编辑活动
- GET /api/activity/detail?id={id} — 活动详情
- POST /api/activity/updateStatus — 上下架

## 会员域
- POST /api/member/list — 会员列表
- GET /api/member/detail?id={id} — 会员详情
- POST /api/member/update — 编辑会员
- POST /api/member/export — 导出

方式三：让 AI 从现有代码提取（最快）

扫描 src/services/ 目录下所有文件，
提取所有接口调用，整理成接口清单：
- [HTTP方法] [路径] — [功能描述]
按业务域分组。

配置好之后的效果

之前：

我：帮我写活动列表页的 service 层
AI：接口地址是什么？请求方式是什么？参数结构是什么？
我：（翻文档，复制粘贴一大段）

之后：

我：帮我写活动列表页的 service 层，用到 list 和 updateStatus 两个接口
AI：（直接生成完整的 service 文件，类型定义正确）

可直接抄走的 Service 模板

AI 生成 service 文件时遵循这个结构：

// src/services/marketing/activity.ts
import request from '@/api/axios'

// ============ 类型定义 ============

/** 活动列表请求参数 */
interface GetActivityListParams {
  pageNum: number
  pageSize: number
  activityName?: string
  status?: number
}

/** 活动列表响应 */
interface GetActivityListResult {
  list: ActivityItem[]
  total: number
}

/** 活动项 */
interface ActivityItem {
  id: number
  activityName: string
  activityType: number
  status: number
  startTime: string
  endTime: string
}

// ============ 接口函数 ============

/** 获取活动列表 */
export const getActivityList = (params: GetActivityListParams) =>
  request.post<GetActivityListResult>('/api/activity/list', params)

/** 更新活动状态 */
export const updateActivityStatus = (data: { id: number; status: number }) =>
  request.post('/api/activity/updateStatus', data)

接口变更时怎么同步

# 方案一：定期从 Swagger 拉取（加到 package.json scripts）
"scripts": {
  "api:sync": "curl -o docs/api-spec.json https://your-backend/v3/api-docs"
}

# 方案二：后端改接口时手动更新清单（1 分钟的事）

一句话总结：让 AI 记住你的接口信息，每次写 service 层就不用再翻文档了。5 分钟配置，省下几百次查文档的时间。

💬 你们团队的接口文档是怎么管理的？前端写类型定义是手动写还是有自动化方案？