cnb-api-generate

基于 swagger2.0 生成 TypeScript 代码与 Agent Skill 的工具。

• cag：生成基于 @cnb/request 和 @reduxjs/toolkit 的 TypeScript 代码，Interface / Enum 与 swagger.json 强绑定。
• csg：基于 swagger 生成 Agent Skill（SKILL.md + CLI）。

为什么需要

前后端各维护一套接口定义时，后端 swagger.json 变更无法触达前端：编译能过，运行时才报错；Interface / Enum 靠手写，容易写错或重复定义。

使用本工具后，Interface / Enum 与请求函数全部由 swagger.json 生成，swagger.json 一变重新生成即可在编译期发现类型错误，同时自动生成 jsDoc 注释。

安装

npm install @cnbcool/cnb-api-generate -D
# or
yarn add @cnbcool/cnb-api-generate -D

必须搭配 @cnb/request 使用。

快速使用

在运行 cag 的目录下创建 cag.config.js：

module.exports = {
  target: '<swagger.json 文件地址>',
}

npx cag
# or
yarn cag

cag.config.js

target

swagger.json 的文件位置，相对 cag.config.js。

outputDir

生成代码的输出目录，相对 cag.config.js。

printeReduxAction

是否输出 Redux Action 代码，默认 true。

requestDependencyMap

自定义请求模块中依赖的函数与 TypeScript 定义。

[key in string]: {
  path: string;
  isDefault: boolean;
}

基于 @cnb/request 已内置，无需配置。

生成 SKILL

文件配置

module.exports = {
  target: './template/swagger.json',
  skillsOutputDir: `./`,
}

执行命令

npx csg

生成目录结构：

| SKILL.md
| scripts/
| - core/
| - modules/

环境变量依赖

• CNB_API_ENDPOINT：可选，自定义 API 地址（默认 https://api.cnb.cool）
• CNB_TOKEN：OpenAPI 令牌
• CNB_WEB_ENDPOINT：与 CNB_API_ENDPOINT 对应的根域名（默认 https://cnb.cool）
• CNB_SSL_NO_VERIFY：设为 true 时跳过 HTTPS 证书校验，适用于自签证书或私有化部署；仅作用于 cnb 自身请求，git 的 clone/push 需另配 http.sslVerify=false

skills list 命令

生成的 Skill 内置 cnb skills list，用于列出本地 skills：

cnb skills list -p -a codebuddy --json