API Adapt

一个 Claude Code Skill，读取 Swagger/OpenAPI 文档，自动学习你项目的代码风格，生成与现有代码一致的 API 数据层代码。

它是什么： 告诉它你要对接哪个接口，它会生成看起来像你团队手写的 API 调用代码 -- 而不是生成器风格的代码。

怎么用： 在 Claude Code 中直接说「帮我对接 /api/user/create 这个接口，swagger 在 xxx」即可触发。

核心功能：

• 学习 -- 自动分析项目数据层风格，输出可编辑的风格档案
• 匹配 -- 解析 Swagger 文档，智能搜索和提取接口定义
• 生成 -- 基于风格档案生成代码，展示 diff，确认后写入
• 增量更新 -- 检测已有接口，仅更新变化的字段

支持任意编程语言。传统工具（swagger-codegen、openapi-generator）生成的是工具自己风格的代码；API Adapt 先学你的风格，再按你的风格生成。

功能特性

• 自动学习项目现有数据层的编码风格，输出可编辑的风格档案
• 解析 Swagger 2.0 / OpenAPI 3.x 文档（URL 或本地文件）
• 模糊搜索、模块搜索、精确路径查询、按 Tag 批量提取
• 智能关键词扩展，解决业务术语与文档命名不一致的问题
• 增量生成：自动检测已有接口，仅更新变化部分
• 严格保留 Swagger 原始字段名，确保前后端一致
• 先展示 diff，用户确认后才写入文件

目录结构

skills/api-adapt/
├── SKILL.md                              # Skill 定义与完整说明
├── README.md                             # 本文件
├── agents/
│   ├── style-learner.md                  # 风格学习 Agent
│   └── code-generator.md                 # 代码生成 Agent
├── references/
│   ├── api-style-template.md             # 风格档案模板与示例（JS/TS）
│   ├── api-style-template-kotlin.md      # 风格档案模板（Kotlin）
│   └── swagger-guide.md                  # Swagger/OpenAPI 解析参考
├── scripts/
│   └── fetch_api.py                      # Swagger 解析与搜索脚本
└── evals/
    └── evals.json                        # 评估用例

工作原理

/api-adapt 调用
    |
    |-- 阶段一：学习（Learn）
    |   检测语言 -> 扫描数据层目录 -> 输出风格档案 .claude/api-style.md
    |   （每个项目只需一次，可随时用 --learn 重新学习）
    |
    |-- 阶段二：匹配（Match）
    |   解析 Swagger/OpenAPI -> 关键词扩展 -> 搜索匹配接口 -> 提取结构化定义
    |   （通过 scripts/fetch_api.py 执行，避免大型 JSON 占用上下文）
    |
    |-- 阶段三：生成（Generate）
    |   风格档案 + 接口定义 -> 检查已有接口 -> 展示 diff -> 确认后写入
    |   （模仿项目风格，不添加示例中没有的东西）
    |
    +-- 完成

快速开始

# 首次使用 -- 自动学习项目风格并搜索接口
/api-adapt ./swagger.json "用户登录"

# 从 URL 获取 Swagger 文档
/api-adapt http://example.com/swagger/doc.json "媒体上传"

首次运行时，skill 会自动扫描项目数据层代码，生成风格档案 .claude/api-style.md 并请你确认。之后的调用将直接使用已有的风格档案。

更多用法

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

# 精确路径查询
/api-adapt ./swagger.json /api/web/media/add

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

# 关键词搜索
/api-adapt ./swagger.json "签到配置"

安装

将 api-adapt 目录复制到 Claude Code 的 skills 目录中：

# 项目级安装（仅当前项目可用）
cp -r skills/api-adapt .claude/skills/api-adapt

# 全局安装（所有项目可用）
cp -r skills/api-adapt ~/.claude/skills/api-adapt

依赖

• Python 3.x（用于运行 scripts/fetch_api.py）
• Claude Code CLI

不在范围内

• 不生成后端代码
• 不生成 UI 组件
• 不在项目没有 model 层时强制生成 model
• 不适用于没有现有数据层代码可学习的全新项目

许可

与主项目保持一致。