S2R

从 Swagger/OpenAPI 文档自动生成 TypeScript API 客户端代码，支持 Mock 服务和 AI 文档转换。

安装

npm install -g s2r

基本使用

生成 API 客户端

# 从文件生成
s2r generate ./swagger.json --output ./src/api

# 从 URL 生成
s2r generate https://api.example.com/swagger.json --output ./src/api

使用生成的代码

import { apiUsersGet, apiUsersPost } from './src/api';

// 调用 API
const users = await apiUsersGet({ page: 1, limit: 10 });
const newUser = await apiUsersPost({ name: 'John', email: '[email protected]' });

拦截器系统

import { InterceptorManager, createAuthInterceptor } from 's2r';
import axios from 'axios';

const axiosInstance = axios.create();
const interceptorManager = new InterceptorManager(axiosInstance);

// 添加认证拦截器
interceptorManager.register({
  request: [createAuthInterceptor({ type: 'bearer', token: 'your-token' })]
});

启动 Mock 服务

s2r mock ./swagger.json --port 3001

访问 http://localhost:3001/docs 查看 Swagger UI。

生成 AI 文档

s2r ai-docs ./swagger.json --output ./docs/api.md

配置文件

创建 .s2r.json：

{
  "swagger": {
    "source": "./swagger.json"
  },
  "generation": {
    "outputDir": "./src/api",
    "typescript": true
  },
  "runtime": {
    "baseURL": "https://api.example.com",
    "timeout": 10000
  }
}

然后运行：

# 默认会读取当前目录下的 .s2r.json
s2r generate

# 显式指定配置文件时，--config 优先
s2r generate --config ./config/s2r.config.json

命令行选项

# 生成代码
s2r generate [source] [options]
  --output, -o     输出目录
  --config, -c     配置文件路径

# Mock 服务
s2r mock [source] [options]
  --port, -p       端口号 (默认: 3001)
  --no-ui          禁用 Swagger UI (默认启用)

# AI 文档
s2r ai-docs [source] [options]
  --output, -o     输出文件路径
  --format, -f     输出格式 (markdown|json|yaml|llm)
  --preset, -p     预设配置 (developer|reference|training|preview|llm)

# 验证文档
s2r validate [source] [options]
  --config, -c     配置文件路径
  --verbose, -v    显示详细验证结果

# 发布 NPM 包
s2r publish [source] [options]
  --name, -n       包名
  --version, -v    版本号

许可证

MIT License