api-adapt

name

api-adapt

description

Generate data-layer code (API calls, models, types) that matches your project's existing coding style by learning from your codebase and reading Swagger/OpenAPI docs. Use this skill whenever the user mentions Swagger, OpenAPI, API integration, generating API client code, creating service layers, data-layer code generation, or wants to connect frontend/mobile code to a backend API. Also activate when the user says things like "add this endpoint", "update the API types", "sync with the backend", "对接接口", "生成API代码", "同步Swagger", "Flutter API", "Retrofit 接口", "Swift 网络层", "Android API 层", or asks about matching their project's API coding patterns — even if they don't explicitly mention "Swagger" or "OpenAPI".

API Adapt — 智能 API 代码适配

生成与项目现有风格一致的数据层代码 —— 看起来就像团队成员手写的，而不是生成器吐出来的。

传统工具（swagger-codegen、openapi-generator）生成的是工具自己风格的代码。API Adapt 会先学习你项目的实际编码模式，再按这个模式生成代码，天然融入项目。

工作原理

三个阶段，依次进行：

阶段一：学习（Learn）

分析项目已有的数据层代码，输出风格档案 .claude/api-style.md。每个项目只需学习一次，捕获以下所有维度：

• 语言与框架
• HTTP 客户端库、封装方式、精确 import 路径
• 文件组织（领域文件夹 / 扁平 / 混合 / 自动生成）
• 文件、函数/方法、类型的命名规则
• 代码是手写还是自动生成的（以及用的什么工具）
• 请求配置对象的完整结构（HTTP 客户端接受的所有 key）
• Model/类型层是否存在、位置、命名规则
• 实例导出模式（针对类风格的 API）
• 特殊模式：filterParam、文件上传、取消令牌、认证方式
• 从项目中逐字复制的真实代码示例（附源文件路径）

用户确认（可编辑）后生效。随时用 --learn 重新学习。

详细流程见 agents/style-learner.md。输出格式规范和两个完整示例（JS 手写 + TS 生成）见 references/api-style-template.md。

阶段二：匹配（Match）

解析 Swagger/OpenAPI 文档（URL 或本地 JSON 文件），找到用户需要的接口，提取结构化的接口定义。

执行工具：scripts/fetch_api.py

Match 阶段通过脚本执行，避免将大型 Swagger JSON（1-5MB）全量加载到对话上下文中。

Python 命令检测（必须先执行）：

在首次调用脚本前，先检测系统使用 python3 还是 python：

# 检测可用的 Python 命令
command -v python3 >/dev/null 2>&1 && PYTHON=python3 || PYTHON=python

后续所有脚本调用均使用 $PYTHON 替代硬编码的 python。

# 列出所有接口（按 tag 分组）
$PYTHON scripts/fetch_api.py --file swagger.json --list

# 模糊搜索（匹配路径、名称、描述、标签）
$PYTHON scripts/fetch_api.py --file swagger.json --search "签到配置"

# 按模块搜索（匹配 tag 名称或 URL 路径段）
$PYTHON scripts/fetch_api.py --file swagger.json --module "账号"
$PYTHON scripts/fetch_api.py --file swagger.json --module "checkin"

# 精确路径查询
$PYTHON scripts/fetch_api.py --file swagger.json --path /api/web/acc/list

# 查看完整定义（入参/出参展开）
$PYTHON scripts/fetch_api.py --file swagger.json --path /api/web/acc/list --detail

# 按 tag 批量提取，输出 JSON 供 Generate 阶段使用
$PYTHON scripts/fetch_api.py --file swagger.json --tag "账号" --json

# 从 URL 获取
$PYTHON scripts/fetch_api.py --url http://host/swagger/doc.json --search "媒体"

脚本能力：

• 支持 Swagger 2.0 和 OpenAPI 3.x
• 递归解析 $ref（含循环引用防护）
• 展开 allOf 组合引用（Go swag 常见的 description + $ref 模式）
• 提取 Go 枚举扩展（x-enum-comments / x-enum-varnames）
• 清理 Go 包前缀（proto.MediaPageReq → MediaPageReq）
• 标记 GET+body 等非标准用法
• --json 输出结构化数据，直接供 code-generator agent 消费

搜索策略：

模式	命令	匹配范围
精确路径	--path /api/web/acc/list	paths 键精确/模糊匹配
关键词搜索	--search "签到"	路径 + summary + description + tags
模块搜索	--module "账号"	tag 名称 → URL module 段 → URL 任意段
Tag 批量	--tag "漫画"	tag 名称精确/模糊匹配

关键词扩展（必须执行）：

使用 --search 或 --module 搜索时，必须先对用户的搜索词做关键词扩展，然后通过 --terms 传入。这是因为用户的业务术语和 Swagger 文档中的命名往往不一致（如"会员卡" vs "VIP卡" vs "card"）。

扩展步骤：

1. 将用户搜索词拆分为独立概念（如"会员卡删除" → "会员卡" + "删除"）
2. 对每个概念生成同义词：中文近义词、英文翻译、常见缩写、领域术语
3. 用 | 连接不同概念组（AND），用 , 连接同一概念的同义词（OR）
4. 传入 --terms 参数

示例：

# 用户说 "会员卡删除"
# 扩展: 会员卡/VIP卡/card/vip | 删除/del/delete/remove
$PYTHON scripts/fetch_api.py --file swagger.json --search "会员卡删除" \
  --terms "会员卡,VIP卡,card,vip,member|删除,del,delete,remove"

# 用户说 "签到配置"
# 扩展: 签到/checkin/sign/check-in | 配置/config/setting/set
$PYTHON scripts/fetch_api.py --file swagger.json --search "签到配置" \
  --terms "签到,checkin,sign,check-in|配置,config,setting,set"

当 Swagger 文档不完整（缺少请求/响应定义）时，脚本会在输出中标记缺失，由 agent 反馈用户手动补充。

Swagger 2.0 与 OpenAPI 3.0 的差异、Go 后端模式、类型名清理规则详见 references/swagger-guide.md。

阶段三：生成（Generate）

将风格档案与 Swagger 接口定义结合，生成代码。遵循以下规则：

1. 模仿，不要发挥。 生成代码中的每一个模式（import、命名、结构、错误处理）都必须来自 api-style.md 中的示例。项目不定义 model 就不生成 model。项目用命名函数就不要用类方法。

2. 默认增量。 生成前先检查项目中是否已存在该接口（搜索 URL 路径字符串）。已存在且无变化 —— 告知无需修改。字段有变化 —— 展示字段级 diff。只为真正的新接口创建新文件。

3. 先展示再写入。 始终展示将要变更的内容和文件位置。用户确认后才写入。

4. 推断文件位置。 根据 api-style.md 中描述的目录结构 + 接口的领域（从 URL 路径或 Swagger 标签提取）推荐文件位置。

完整生成流程见 agents/code-generator.md。

使用方式

# 首次使用 —— 自动学习项目风格
/api-adapt <swagger-url-or-path> "媒体上传接口"

# 强制重新学习项目风格
/api-adapt --learn

# 精确路径
/api-adapt http://example.com/swagger/doc.json /api/web/media/add

# 关键词搜索
/api-adapt ./swagger.json "用户登录"

# 按模块批量
/api-adapt http://example.com/swagger/doc.json --module user

流程图

/api-adapt 调用
    │
    ├─ .claude/api-style.md 是否存在？
    │   ├─ 否 → 运行风格学习 → 用户确认 → 保存
    │   └─ 是 → 加载风格档案
    │
    ├─ 解析 Swagger 输入（URL 或文件）
    │   ├─ 成功 → 提取匹配的接口
    │   └─ 失败 → 清晰的错误提示
    │
    ├─ 对每个接口：
    │   ├─ 项目中已存在？
    │   │   ├─ 是，无变化 → "无需修改"
    │   │   ├─ 是，字段有变化 → 展示字段 diff → 确认 → 更新
    │   │   └─ 否 → 生成新代码 → 展示 diff → 确认 → 写入
    │   │
    │   └─ Swagger 定义不完整？
    │       → 报告缺失部分 → 请用户描述 → 继续
    │
    └─ 完成

本 Skill 不做的事

• 生成后端代码
• 生成 UI 组件
• 在项目没有 model 层时强制生成 model
• 在没有现有数据层代码可学习的新项目上工作

附带资源

资源	何时阅读
agents/style-learner.md	运行学习阶段时
agents/code-generator.md	运行生成阶段时
references/swagger-guide.md	解析 Swagger/OpenAPI 文档时
references/api-style-template.md	生成或验证 api-style.md 时