告别手动对接口：我用 OpenAPI JSON 做了一个前端接口同步 Skill

从 Apifox 到 TypeScript：让 AI 自动同步前端接口定义

背景

在前后端协作开发中，后端通常会先在 Apifox 中维护接口文档。版本迭代时，例如 v5.1.3，后端会在接口名中标记版本号，前端再根据文档更新项目中的接口定义和类型定义。

传统流程通常是：

打开 Apifox 文档
搜索当前版本接口
逐个查看请求参数和响应参数
手动更新 src/api
手动更新 src/types
再执行类型检查或构建验证

这个过程虽然可控，但很容易出现漏字段、类型写错、接口路径不同步、可选字段判断错误等问题。

因此，我整理了一个 Codex Skill：openapi-json-sync，用于把 Apifox/OpenAPI 契约同步到前端 TypeScript 项目中。

这个 Skill 解决什么问题

openapi-json-sync 的目标很明确：

根据 Apifox/OpenAPI JSON 自动同步前端项目的 src/api 和 src/types。

它不会强制全量生成 API Client，也不会替换项目原有架构，而是读取项目现有代码风格，按当前项目习惯增量更新接口方法和类型定义。

适合以下场景：

前端项目使用 TypeScript
项目中已有 src/api 和 src/types
后端接口文档维护在 Apifox
前端希望减少人工对照接口文档的工作
希望 AI 基于完整接口契约同步，而不是根据截图或口头描述猜字段

核心设计

openapi-json-sync 支持两种同步方式。

方式一：手动导出 OpenAPI JSON

这是最简单稳定的方式。

前端开发先从 Apifox 手动导出当前版本相关接口的 OpenAPI JSON，然后告诉 AI 文件位置。

示例：

text 复制代码

使用 openapi-json-sync。
JSON：.cache/apifox/openapi-v5.1.3.json
同步：应收报表相关接口

这种模式下：

用户提供的 JSON 就是最终同步范围
Skill 不会再做版本过滤
AI 直接读取 JSON
AI 读取项目现有 src/api / src/types 风格
AI 根据 JSON 更新接口方法和类型定义
AI 自动执行类型检查或构建验证

方式二：Apifox CLI 自动导出

如果不想每次手动导出，也可以让 AI 使用 Apifox CLI 自动导出完整项目 OpenAPI JSON。

首次使用示例：

text 复制代码

使用 openapi-json-sync。
Apifox token：xxx
Apifox 项目 ID：123456
版本：hjs_v5.1.3
同步：应收报表相关接口

Skill 会执行：

使用 Apifox CLI 登录
保存项目 ID 到 .apifox/settings.json
导出完整 OpenAPI JSON 到 .cache/apifox/openapi.raw.json
使用内置脚本按版本 token 过滤接口
使用过滤后的 JSON 同步 src/api 和 src/types

后续已配置项目 ID 后，可以简化为：

text 复制代码

用 openapi-json-sync，从 Apifox 同步 hjs_v5.1.3 应收报表相关接口。

版本过滤规则

版本过滤只用于 Apifox CLI 模式。

手动导出的 JSON 已经是最终同步范围，不会再执行过滤脚本。

CLI 模式下，Skill 会根据用户给出的版本 token 精确匹配接口名。

例如：

text 复制代码

版本：v5.1.3

只匹配接口名中包含 v5.1.3 的接口。

text 复制代码

版本：hjs_v5.1.3

只匹配接口名中包含 hjs_v5.1.3 的接口。

text 复制代码

版本：hjs_v5.1.3,hjs_v5.1.4

匹配接口名中包含任意一个版本 token 的接口。

不会自动扩展版本号：

v5.1.3 不会自动匹配 hjs_v5.1.3
hjs_v5.1.3 不会自动匹配 v5.1.3

这样可以避免误匹配。

同步规则

Skill 同步代码时遵循以下原则：

OpenAPI JSON 是唯一接口契约来源
不根据截图、口头描述或历史记忆补字段
新增接口时新增 API 方法和请求/响应类型
修改接口时更新字段类型、可选性、数组、对象、枚举说明
保持项目已有响应包装类型，例如 CustomResponse<T>
尽量只改 src/api 和 src/types
除非类型检查必须，不修改业务页面
不生成 Markdown 变更报告
不全量覆盖现有 API/type 文件

自动验证策略

同步完成后，Skill 会自动从 package.json 中选择合适的验证命令。

优先级通常是：

text 复制代码

type-check / vue-tsc
build:test
build

默认不会执行长期运行命令：

text 复制代码

dev
serve
preview
start

也不会默认执行会改写文件的命令：

text 复制代码

lint --fix
format
prettier --write

项目配置

Apifox CLI 模式建议使用配置文件：

json 复制代码

{
  "projectId": "123456",
  "branch": "main",
  "rawOutput": ".cache/apifox/openapi.raw.json",
  "filteredOutputPattern": ".cache/apifox/openapi-{version}.json"
}

保存路径：

text 复制代码

.apifox/settings.json

注意：

projectId 可以保存
token 不保存
token 不提交到 Git
.cache/apifox/ 建议加入 .gitignore

总结

openapi-json-sync 的核心价值是：

减少前端手动对照 Apifox 文档的时间
降低接口字段漏同步的概率
保持项目现有 API/type 风格
让 AI 基于完整 OpenAPI 契约工作
支持手动 JSON 和 Apifox CLI 两种同步方式

它不是为了替代项目现有 API 架构，而是让接口同步这件事更稳定、更高效、更可复用。

仓库地址

Gitee：

gitee.com/linyinneng/...

告别手动对接口：我用 OpenAPI JSON 做了一个前端接口同步 Skill

从 Apifox 到 TypeScript：让 AI 自动同步前端接口定义

背景

这个 Skill 解决什么问题

核心设计

方式一：手动导出 OpenAPI JSON

方式二：Apifox CLI 自动导出

版本过滤规则

同步规则

自动验证策略

项目配置

推荐用法

总结

仓库地址