English | 中文

cli-openapi

一条命令，将 OpenAPI 3.x 规范生成为完整的 Commander.js TypeScript CLI 项目。

功能特性

• 支持从文件路径或 URL 解析 OAS 3.x 规范（完整 $ref 解析）
• 按 tag 分组操作，生成 Commander 子命令组；未分组的操作注册为顶层命令
• 生成带完整类型标注的 TypeScript 源码，支持必填/可选参数、枚举 .choices() 校验
• 5 种认证方案自动从 OAS 安全定义中检测：Bearer、API Key、HTTP Basic、OAuth2 Client Credentials、自定义动态 Token
• SSE 流式输出基于 @microsoft/fetch-event-source，支持自动重连和 [DONE] 哨兵处理
• 自动分页：--all-pages 参数，自动跟随 Link: rel="next" 响应头翻页
• JMESPath 过滤：每条命令均支持 --query 参数
• 中文命令名支持：中/日/韩 operationId 自动转换为拼音
• OpenAPI 扩展：x-cli-name、x-cli-aliases、x-cli-ignore、x-cli-token-url
• 自动生成双语文档：README.md（英文）+ README.zh.md（中文）+ SKILL.md（Claude Code 技能描述文件）
• 所有生成的 CLI 均内置全局选项：--endpoint、--format（json/yaml/table）、--verbose

安装

npm install -g cli-openapi

使用方法

# 从本地文件生成
cli-openapi generate --oas ./openapi.yaml --name my-api --output ./my-api-cli

# 从 URL 生成
cli-openapi generate --oas https://petstore3.swagger.io/api/v3/openapi.json --name petstore --output ./petstore-cli

构建并链接生成的项目：

cd my-api-cli
npm install && npm run build && npm link
my-api --help

示例

参见 examples/github-cli/，这是一个针对 GitHub REST API 的完整生成示例：

cd examples/github-cli
npm install && npm run build
node dist/index.js repos get-repo --owner octocat --repo Hello-World
node dist/index.js repos list-repo-issues --owner octocat --repo Hello-World --state open
node dist/index.js users get-user --username octocat

生成项目结构

<output>/
├── bin/<name>            # 可执行文件 shebang 包装器
├── src/
│   ├── index.ts          # Commander 根程序 + 全局选项
│   ├── commands/
│   │   └── <tag>.ts      # 每个 OAS tag 对应一个文件
│   └── lib/
│       └── api-client.ts # 带认证 + SSE 流式支持的 axios 客户端
├── README.md             # 英文使用文档
├── README.zh.md          # 中文使用文档
├── SKILL.md              # Claude Code 技能描述文件
├── package.json
└── tsconfig.json

生成项目的运行时依赖：axios、chalk、commander、@microsoft/fetch-event-source、jmespath、yaml、ora。

认证方式

生成器自动检测 OAS 文档中的第一个安全方案，并生成对应的认证代码。运行 CLI 前设置相应的环境变量：

| 方案 | 环境变量 | 说明 | |------|---------|------| | Bearer | <NAME>_TOKEN | Authorization: Bearer … | | API Key | <NAME>_API_KEY | Header 或 Query 参数，名称取自 OAS | | HTTP Basic | <NAME>_CREDENTIALS | 用户名:密码 → Base64 编码 | | OAuth2 Client Credentials | <NAME>_CLIENT_ID、<NAME>_CLIENT_SECRET、<NAME>_SCOPES | 启动时自动换取 Token，进程内缓存 | | 动态 Token（x-cli-token-url） | 扩展字段中定义的自定义环境变量 | 以 JSON Body 请求 Token 端点 |

<NAME> 为 CLI 名称的大写下划线形式（如 my-api → MY_API）。

OpenAPI 扩展

在 OAS 文档中添加以下厂商扩展，可控制 CLI 生成行为：

| 扩展字段 | 位置 | 效果 | |----------|------|------| | x-cli-name: "my-name" | operation | 覆盖自动生成的命令名 | | x-cli-aliases: ["a"] | operation | 为命令添加 Commander 别名 | | x-cli-ignore: true | operation | 从生成的 CLI 中排除该操作 | | x-cli-token-url: "https://…" | securityScheme | 自定义动态认证 Token 端点 |

全局选项

所有生成的 CLI 的每条命令均支持以下全局选项：

| 选项 | 说明 | 默认值 | |------|------|--------| | --endpoint <url> | 覆盖 API 基础地址 | OAS 规范中的 server URL | | --format <fmt> | 输出格式：json、yaml、table | json | | --verbose | 打印每次请求的 HTTP 方法和 URL | false | | --query <expr> | JMESPath 表达式，过滤响应结果 | — | | --all-pages | 自动翻页（跟随 Link: rel="next" 响应头） | false |

请求体

POST、PUT、PATCH 命令使用 --data 传入请求体：

# 内联 JSON
my-api widgets create --data '{"name": "foo", "color": "blue"}'

# 从文件读取
my-api widgets create --data @./payload.json

输出格式

# 默认：格式化 JSON
my-api repos list

# 表格视图（适合数组类型数据）
my-api repos list --format table

# YAML 格式
my-api repos list --format yaml

# JMESPath 过滤
my-api repos list --query '[].name'

# 配合 jq 过滤
my-api repos list | jq '.[].full_name'

# 保存到文件
my-api repos list > repos.json

流式输出（SSE）

响应内容类型为 text/event-stream 的操作会被自动识别。生成的 CLI 将每个 SSE 数据载荷输出到 stdout，每行一条：

my-api completions create --model gpt-4o --stream

生成的客户端使用 @microsoft/fetch-event-source，可在网络中断时自动重连，并遵守服务端 retry: 字段的退避策略。OpenAI 兼容 API 常用的 [DONE] 哨兵会被静默丢弃。

生成器 CLI 选项

cli-openapi generate [options]

选项：
  --oas <path|url>   OpenAPI 3.x 规范的文件路径或 URL（必填）
  --name <name>      CLI 可执行文件名称（必填）
  --output <dir>     输出目录（必填）
  --overwrite        覆盖已存在的输出目录
  -h, --help         显示帮助信息

许可证

MIT