@fxri/swagger2api 1.3.0 → 1.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +71 -0
- package/README.md +124 -115
- package/dist/cli.cjs +33 -7
- package/dist/cli.js +33 -7
- package/dist/index.cjs +22 -3
- package/dist/index.js +22 -3
- package/dist/templates/api.ejs +41 -3
- package/dist/templates/procedure-call.ejs +11 -3
- package/package.json +5 -3
- package/skills/fxri-swagger2api/SKILL.md +51 -0
- package/skills/fxri-swagger2api/references/cli.md +40 -0
- package/skills/fxri-swagger2api/references/config.md +59 -0
- package/skills/fxri-swagger2api/references/migration.md +41 -0
- package/skills/fxri-swagger2api/references/output.md +32 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,76 @@
|
|
|
1
1
|
# Swagger 转 API
|
|
2
2
|
|
|
3
|
+
## 1.3.2
|
|
4
|
+
|
|
5
|
+
> 2026-11-21 发布
|
|
6
|
+
|
|
7
|
+
### 🐛 问题修复
|
|
8
|
+
|
|
9
|
+
- 支持 `defaults` + `targets` 多目标配置,一条命令生成或校验全部目标,`--target <id>` 只执行指定目标
|
|
10
|
+
- 多目标生成前整体预校验 `id`、输入与输出目录,冲突时以退出码 2 结束且不写任何目标
|
|
11
|
+
- 新增 `surface` 命令,提取产物中的 `@request` / `@name` 与导出类型,支持 `--out` 写基线、`--compare` 比对增删
|
|
12
|
+
- 多目标按 `id` 分组,目标集合或格式版本变化按失败处理;`--requests-only` 只锁接口集合
|
|
13
|
+
- 新增 `typeCheck`(扁平)/ `output.typeCheck`(嵌套)配置,`enforce` 时在写盘后剥离 `.ts` / `.js` / `.d.ts` 中的 `// @ts-nocheck`
|
|
14
|
+
- `--check` 的临时产物走同一剥离处理后再比对,避免与真实产物误报不一致
|
|
15
|
+
|
|
16
|
+
## 1.3.1
|
|
17
|
+
|
|
18
|
+
> 2026-11-21 发布
|
|
19
|
+
|
|
20
|
+
### ✨ 新增功能
|
|
21
|
+
|
|
22
|
+
- 项目层默认配置文件改为 `swagger2api.json`,本地层 `swagger2api.local.json`,全局层 `~/.swagger2api.json`;旧名继续可用
|
|
23
|
+
- 同目录新旧配置并存时新名优先并告警,`init` / `grouping` 默认写入新名
|
|
24
|
+
- 契约按业务文件拆分,单归属进 `types/<业务文件>.ts`,多归属与未使用进 `types/shared.ts`
|
|
25
|
+
- `types/index` 改为显式导出 barrel,内部声明只在本文件导出、不进入公开面
|
|
26
|
+
- `grouping.collapse` 合并折叠键相同的组,复现单文件产物「同名属性即同组」的语义
|
|
27
|
+
- `output.prune`(`--prune-output`)按上一轮生成清单清理已消失的模块,不触碰手写文件与清单外产物
|
|
28
|
+
- `grouping.split` 自适应分桶与命名空间分片,按接口体量压缩模块文件数
|
|
29
|
+
- 分片门面以实例合并与类型合并保持 `api.<命名空间>.<方法>` 调用形态不变
|
|
30
|
+
- `--dry-run --json` 报表输出桶与分片规划,拆分结果可先预览
|
|
31
|
+
- 扁平 `swagger2api.json` 配置,业务仓只写项目口径,分组阈值与桶名由工具默认
|
|
32
|
+
- `--check` 生成到临时目录并与现有产物逐文件比对,不写真实目录
|
|
33
|
+
- `verify` 校验技能打包与定位(`files` / `skill` 命令 / npm 包内容),并调用全局 toolkit `skills lint`
|
|
34
|
+
- 包内技能 `skills/fxri-swagger2api/`,覆盖首次接入、旧配置迁移与产物结构判断
|
|
35
|
+
- `swagger2api skill` / `--print` / `--json` 只读定位技能入口,不写文件、不维护状态
|
|
36
|
+
- 契约出口固定为 `types/index`,聚合入口按 `export * from "./types"` 导出
|
|
37
|
+
- 旧版 `data-contracts` / `http-client` 残留会在生成成功后自动清理
|
|
38
|
+
|
|
39
|
+
### 🔧 功能调整
|
|
40
|
+
|
|
41
|
+
- 装箱后小于下限的桶与相邻桶合并(优先前一桶,且不超过上限),消除大命名空间夹出的碎片文件
|
|
42
|
+
- 手动 `--modular` 也按本轮生成文件写入清单,连续生成清理已消失模块
|
|
43
|
+
- `--check` 覆盖手动模式,能发现缺失与过期产物
|
|
44
|
+
- 分组产物底座改名,`http-client` 改为 `client`,`data-contracts` 改为 `types/` 目录
|
|
45
|
+
|
|
46
|
+
### ⚡ 优化改进
|
|
47
|
+
|
|
48
|
+
- `init` 的 `.gitignore` 片段新增本地配置忽略项,已有片段按需补齐
|
|
49
|
+
- JS 模式的运行时枚举随归属文件落盘,出口同步 re-export
|
|
50
|
+
- `typescript` 提升为运行时依赖,用于按声明解析契约引用
|
|
51
|
+
- 生成清单移入系统缓存且不再记录工具名与版本,产物目录保持干净
|
|
52
|
+
- toolkit 低于 1.17.6 或不可用时降级为本仓硬断言,并在 stderr 提示安装或升级
|
|
53
|
+
- `files` 白名单纳入 `skills` 并声明 `agentSkills`,技能随 npm 包发布
|
|
54
|
+
- 产物清单、按清单清理与手写护栏支持 `types/` 嵌套路径
|
|
55
|
+
|
|
56
|
+
### 🐛 问题修复
|
|
57
|
+
|
|
58
|
+
- 分组模块的共享请求器改为公开字段,两个组的类型交叉不再坍缩为 `never`
|
|
59
|
+
- 补分组对外面门禁的交叉类型断言,避免同类回归
|
|
60
|
+
- 分组产物的聚合入口补齐 `AxiosResponse`、`FullRequestParams`、`RequestParams`、`ContentType`、`HttpClient` 导出,包桶引用与单文件产物一致
|
|
61
|
+
- JS 模式分组模块声明补齐 `AxiosResponse` 导入,`AxiosParse` 推导不再退化为 `unknown`
|
|
62
|
+
- 分组模块改为注入聚合请求器,替换 `api.instance` 与 `setSecurityData` 会对所有组同时生效
|
|
63
|
+
- 组名撞上 `instance`、`request` 等聚合成员时改用追加序号,避免覆盖运行期能力
|
|
64
|
+
- `--replace-tags` 值不足时忽略该参数并告警,不再用空串清空 JSDoc 标签
|
|
65
|
+
- 目标模块名已被手写文件占用时终止生成并提示,不再静默覆盖
|
|
66
|
+
- 临时文档改落系统临时目录,`output.clean` 与收尾清理不再报 ENOENT
|
|
67
|
+
- JS 输出的聚合入口不再带泛型与可选参数语法,避免 `.js` 文件出现 TypeScript 写法
|
|
68
|
+
|
|
69
|
+
### 📝 文档更新
|
|
70
|
+
|
|
71
|
+
- 指南新增「AI 技能:什么时候需要」,README 与 `--help` 露出 `skill` 命令
|
|
72
|
+
- AGENTS 增加本仓库能力自举与规范真源说明
|
|
73
|
+
|
|
3
74
|
## 1.3.0
|
|
4
75
|
|
|
5
76
|
> 2026-11-21 发布
|
package/README.md
CHANGED
|
@@ -1,115 +1,124 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="./docs/public/logo.png" width="128" alt="Swagger 转 API">
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
# Swagger 转 API
|
|
6
|
-
|
|
7
|
-
[](https://github.com/fxri-net/swagger2api/actions/workflows/ci.yml)
|
|
8
|
-
[](https://www.npmjs.com/package/@fxri/swagger2api)
|
|
9
|
-
[](./docs/getting-started.md#安装)
|
|
10
|
-
[](./LICENSE)
|
|
11
|
-
[](https://fxri-net.github.io/swagger2api/)
|
|
12
|
-
|
|
13
|
-
> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/swagger2api)(与 GitHub 同源同步);问题反馈走 [GitHub Issues](https://github.com/fxri-net/swagger2api/issues) 或 [Gitee Issues](https://gitee.com/fxri/swagger2api/issues)。
|
|
14
|
-
|
|
15
|
-
基于 [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) 封装的 CLI 工具:Swagger 文档一键转 TS/JS 格式的 API 文件。
|
|
16
|
-
|
|
17
|
-
后端给到 Swagger 文档,接口代码还要照着手写;接口一多重名 `_n` 后缀满屏;多个项目的接口配置散落各处,更新要挨个跑命令。本工具把这些沉淀为**一行命令**:配置落盘可复用,生成静默无感,调用即取即用。
|
|
18
|
-
|
|
19
|
-
- **多文档配置**:自动扫描项目下全部 `saconfig*.json`,多项目接口集中管理,搭配快速模式一行命令全量更新([怎么玩?](./docs/guide.md#多文档配置))
|
|
20
|
-
- **唯一 operationId**:接口地址 + 请求方法拼接,从源头告别 `_n` 重名后缀([拼接规则](./docs/guide.md#唯一-operationid-拼接规则))
|
|
21
|
-
- **不懂生成的代码也能用**:接口文件含请求方法与类型定义,导入即调;参数全部有默认值,交互引导填写([30 秒上手](./docs/getting-started.md))
|
|
22
|
-
|
|
23
|
-
## 🚀 30 秒上手
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
# 1. 首次:交互式写入 .
|
|
27
|
-
pnpm dlx @fxri/swagger2api init
|
|
28
|
-
|
|
29
|
-
# 2. 之后一行生成:读取配置,无参即可;换人 clone 仓库后同样两条命令
|
|
30
|
-
pnpm dlx @fxri/swagger2api
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
| [
|
|
64
|
-
| [
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="./docs/public/logo.png" width="128" alt="Swagger 转 API">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# Swagger 转 API
|
|
6
|
+
|
|
7
|
+
[](https://github.com/fxri-net/swagger2api/actions/workflows/ci.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/@fxri/swagger2api)
|
|
9
|
+
[](./docs/getting-started.md#安装)
|
|
10
|
+
[](./LICENSE)
|
|
11
|
+
[](https://fxri-net.github.io/swagger2api/)
|
|
12
|
+
|
|
13
|
+
> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/swagger2api)(与 GitHub 同源同步);问题反馈走 [GitHub Issues](https://github.com/fxri-net/swagger2api/issues) 或 [Gitee Issues](https://gitee.com/fxri/swagger2api/issues)。
|
|
14
|
+
|
|
15
|
+
基于 [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) 封装的 CLI 工具:Swagger 文档一键转 TS/JS 格式的 API 文件。
|
|
16
|
+
|
|
17
|
+
后端给到 Swagger 文档,接口代码还要照着手写;接口一多重名 `_n` 后缀满屏;多个项目的接口配置散落各处,更新要挨个跑命令。本工具把这些沉淀为**一行命令**:配置落盘可复用,生成静默无感,调用即取即用。
|
|
18
|
+
|
|
19
|
+
- **多文档配置**:自动扫描项目下全部 `saconfig*.json`,多项目接口集中管理,搭配快速模式一行命令全量更新([怎么玩?](./docs/guide.md#多文档配置))
|
|
20
|
+
- **唯一 operationId**:接口地址 + 请求方法拼接,从源头告别 `_n` 重名后缀([拼接规则](./docs/guide.md#唯一-operationid-拼接规则))
|
|
21
|
+
- **不懂生成的代码也能用**:接口文件含请求方法与类型定义,导入即调;参数全部有默认值,交互引导填写([30 秒上手](./docs/getting-started.md))
|
|
22
|
+
|
|
23
|
+
## 🚀 30 秒上手
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# 1. 首次:交互式写入 swagger2api.json(团队共享,可提交)
|
|
27
|
+
pnpm dlx @fxri/swagger2api init
|
|
28
|
+
|
|
29
|
+
# 2. 之后一行生成:读取配置,无参即可;换人 clone 仓库后同样两条命令
|
|
30
|
+
pnpm dlx @fxri/swagger2api
|
|
31
|
+
|
|
32
|
+
# 提交前可校验产物是否与当前配置一致
|
|
33
|
+
pnpm dlx @fxri/swagger2api --check
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
接口规模大时,先 `swagger2api grouping` 选择分组方式,再生成即可输出多文件 + 单一出口,详见[完整攻略 · 分组输出](./docs/guide.md#分组输出)。
|
|
37
|
+
|
|
38
|
+
首次接入、迁移旧配置或调整产物结构时,可让 AI 读取包内技能:`pnpm exec swagger2api skill --print`;日常生成与 `--check` 不需要加载。
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
import { Api } from "./src/api/index"
|
|
42
|
+
|
|
43
|
+
/** 请求器 */
|
|
44
|
+
export const request = new Api()
|
|
45
|
+
request.getUsers().then((res) => console.log(res))
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
完整步骤见 [快速开始](./docs/getting-started.md)。
|
|
49
|
+
|
|
50
|
+
## ✨ 能力矩阵
|
|
51
|
+
|
|
52
|
+
| 能力 | 适用场景 | 文档 |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| 快速生成 | 从 Swagger JSON 生成 TS/JS 接口文件,含请求方法与类型定义 | [快速开始](./docs/getting-started.md) |
|
|
55
|
+
| 多文档配置 | 一份 `swagger2api.json` 用 `targets` 声明多个文档,或扫描 `saconfig*.json` 集中管理 | [配置参考 · 多目标配置](./docs/config.md#多目标配置) |
|
|
56
|
+
| 快速模式 | 配置齐全时跳过二次确认,搭配脚本一行命令静默更新 | [完整攻略](./docs/guide.md#快速模式) |
|
|
57
|
+
| 分层配置与向导 | `swagger2api.json` 项目 / 个人 / 全局三层合并(旧名 `.swagger2apirc.json` 兼容),`init` 向导建设配置,`config status` 排障 | [配置参考](./docs/config.md) |
|
|
58
|
+
| 分组输出 | 大文档按规则 / tag / 路径段拆分为多文件,聚合入口保持单一出口 | [完整攻略](./docs/guide.md#分组输出) |
|
|
59
|
+
| 唯一 operationId | 接口地址 + 请求方法拼接唯一 ID,可选 get 转 query 作区分 | [完整攻略](./docs/guide.md#唯一-operationid-拼接规则) |
|
|
60
|
+
| 灵活裁剪 | 移除路径参数 / 前缀索引、替换标签、移除空组件定义 | [配置参考](./docs/config.md) |
|
|
61
|
+
| 响应提取 | AxiosResponse 转移到 raw 字段,根部字段自行声明 | [完整攻略](./docs/guide.md#提取响应--extract-response-raw-err) |
|
|
62
|
+
| 类型检查接管 | 需要项目类型检查覆盖生成物时剥离 `// @ts-nocheck` | [配置参考](./docs/config.md) |
|
|
63
|
+
| 接口面基线 | 提取产物的接口与类型,跨工具版本迁移时比对增删 | [CLI 参考](./docs/cli.md) |
|
|
64
|
+
| STA 参数透传 | swagger-typescript-api 原生参数全量可用 | [CLI 参考](./docs/cli.md) |
|
|
65
|
+
|
|
66
|
+
## 📚 文档
|
|
67
|
+
|
|
68
|
+
| 文档 | 适合谁 |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| [快速开始](./docs/getting-started.md) | 第一次接触,想 30 秒跑起来 |
|
|
71
|
+
| [完整攻略](./docs/guide.md) | 日常使用:三种模式、响应提取、配置文件 |
|
|
72
|
+
| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值 |
|
|
73
|
+
| [常见问题](./docs/faq.md) | 遇到问题先来这里找 |
|
|
74
|
+
| [完整文档站](https://fxri-net.github.io/swagger2api/) | 在线阅读体验 |
|
|
75
|
+
|
|
76
|
+
## 📦 安装
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pnpm add -D @fxri/swagger2api # 项目依赖(团队推荐,版本随仓库锁定)
|
|
80
|
+
pnpm i -g @fxri/swagger2api # 全局(个人多项目推荐)
|
|
81
|
+
pnpm dlx @fxri/swagger2api # 不安装临时执行
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
npm / yarn 用户、同名工具冲突说明见 [新手指南 · 安装](./docs/getting-started.md#安装)。
|
|
85
|
+
|
|
86
|
+
## 📁 多文档配置
|
|
87
|
+
|
|
88
|
+
同一仓库有多个 Swagger 文档时,推荐一份 `swagger2api.json` 用 `defaults` + `targets` 声明:无参数即生成全部目标,`--check` 校验全部目标,详见[配置参考 · 多目标配置](./docs/config.md#多目标配置)。
|
|
89
|
+
|
|
90
|
+
以下为早期的 saconfig 扫描方式:默认配置文件为 `saconfig.json`;工具会扫描项目下所有 `saconfig*.json`(如 `saconfig.admin.json`、`config/saconfig.json`),多文件时提供选择列表。搭配快速模式与加载全部配置参数,`package.json` 一行脚本即可静默更新所有项目的接口代码:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"scripts": {
|
|
95
|
+
"api": "swagger2api --axios --responses -q -rpi 0 -err -ca"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
此功能扩展使用的话,可以作为一个独立工具使用,同时管理多个项目的接口配置。详见 [完整攻略 · 多文档配置](./docs/guide.md#多文档配置)。
|
|
101
|
+
|
|
102
|
+
## ⚙️ 环境要求
|
|
103
|
+
|
|
104
|
+
- Node.js >= 18.12.0
|
|
105
|
+
|
|
106
|
+
## 🛠️ 开发约定
|
|
107
|
+
|
|
108
|
+
验收统一执行 `pnpm verify`:步骤清单的唯一真源在 `scripts/verify.mjs`,本地与 CI 共用同一份;构建、调试与提交规则见 [AGENTS.md](./AGENTS.md)。
|
|
109
|
+
|
|
110
|
+
## 📄 版权信息
|
|
111
|
+
|
|
112
|
+
作者:唐启云 <tqy@fxri.net>
|
|
113
|
+
|
|
114
|
+
出品:方弦研究所
|
|
115
|
+
|
|
116
|
+
版权:Copyright © 2025-2026 唐启云. All rights reserved.
|
|
117
|
+
|
|
118
|
+
网站:[方弦研究信息网](https://fxri.net:444/)
|
|
119
|
+
|
|
120
|
+
协议:[MIT License](./LICENSE)
|
|
121
|
+
|
|
122
|
+
商标:"方弦®"为第42类注册商标(注册号89648411),本开源许可不授予商标使用权,详见 [TRADEMARK.md](./TRADEMARK.md)
|
|
123
|
+
|
|
124
|
+
> 方弦研究所为唐启云个人项目品牌与出品方,非独立法人实体;本软件著作权归唐启云所有。
|