# openapi-json-sync

**Repository Path**: linyinneng/openapi-json-sync

## Basic Information

- **Project Name**: openapi-json-sync
- **Description**: 从 Apifox OpenAPI JSON 同步前端 TypeScript API 与类型定义。Sync frontend TypeScript API/types from Apifox OpenAPI JSON.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openapi-json-sync

这个 Skill 用于把 Apifox/OpenAPI 契约同步到前端 TypeScript 项目的 `src/api` 和 `src/types`。

它支持两种模式：

- 手动 JSON：你已经从 Apifox 导出 OpenAPI JSON，AI 直接同步。
- Apifox CLI：AI 用 Apifox CLI 导出完整项目 JSON，再按版本 token 过滤后同步。

## 安装

复制整个目录到 Codex skills 目录：

```powershell
Copy-Item -Recurse .\openapi-json-sync C:\Users\13023\.codex\skills\openapi-json-sync
```

## 用法一：手动 JSON

手动 JSON 已经是你要同步的接口范围，不会再经过脚本过滤。

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

一句话：

```text
用 openapi-json-sync，同步 .cache/apifox/openapi-v5.1.3.json 里的接口。
```

## 用法二：Apifox CLI

首次使用：

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

Skill 会：

1. 使用 Apifox CLI 登录。
2. 保存项目 ID 到 `.apifox/settings.json`，但不保存 token。
3. 导出完整项目 OpenAPI JSON 到 `.cache/apifox/openapi.raw.json`。
4. 用 `scripts/filter-openapi-version.mjs` 按版本 token 过滤。
5. 使用过滤后的 JSON 同步 `src/api` 和 `src/types`。

后续已配置项目 ID 后：

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

## 项目配置

CLI 模式建议使用：

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

配置路径：

```text
.apifox/settings.json
```

注意：token 不写入配置文件，不提交到 git。

## 版本过滤规则

过滤脚本只用于 CLI 模式导出的完整 raw JSON。手动 JSON 不过滤。

- 用户给什么版本 token，就按这个 token 匹配接口名。
- 不做版本 token 自动扩展。
  - `v5.1.3` 不自动匹配 `hjs_v5.1.3`
  - `hjs_v5.1.3` 不自动匹配 `v5.1.3`
- 多个版本 token 是 OR 关系。
- 只过滤接口，不过滤字段。
- 命中接口会保留完整 request/response schema 和递归 `$ref`。

脚本示例：

```bash
node C:\Users\13023\.codex\skills\openapi-json-sync\scripts\filter-openapi-version.mjs --input .cache/apifox/openapi.raw.json --versions hjs_v5.1.3,hjs_v5.1.4 --out .cache/apifox/openapi-hjs_v5.1.3-hjs_v5.1.4.json
```

## 同步和验证规则

- 最终 OpenAPI JSON 是唯一接口契约来源。
- 读取项目 API/type 风格后再改代码。
- 不生成 Markdown 变更报告。
- 只同步接口契约层，默认只改 `src/api`、`src/types` 或同类 API/type 文件。
- 不开发业务功能，不主动修改页面、组件、表单、按钮、下拉字典、路由、权限、样式或业务交互。
- 如果构建失败来自页面尚未适配新字段，只报告“调用方待适配”，不要自动补页面功能。
- 自动从 `package.json` 选择一个验证命令，并按锁文件选择 `pnpm`/`npm`/`yarn`/`bun`。
- 默认不跑 `dev`、`serve`、`preview`、`start` 这类长期运行命令。
- 默认不跑会改写文件的 `lint --fix`、`format`、`prettier --write`。

## 不适用场景

- 想用 Orval、openapi-typescript 或 Hey API 全量生成 client。
- 没有 OpenAPI JSON，也没有 Apifox CLI/token/projectId。
- 想批量重构项目 API 架构。