@wx-sab/renkei

解析 swagger 转为 ts 代码，生成可立即使用的 ts 代码，无需手动书写接口定义

日本动漫《游戏王》中的‘Renkei’，意为连携或协作。

Feature

• [x] 支持 swagger 解析
• [x] 支持 apifox 导出 swagger 解析
• [x] 支持多项目/多服务配置
• [x] 支持远程 apifox 远程 Mock
• [x] 多服务的 apifox 项目解析
• [x] 支持 swagger 3.0 解析
• [x] 支持自定义生成接口名
• [x] 支持只生成部分服务接口

Introduce

Install

项目发布在私有的 npm源，故需要更改 npm 源地址为：http://10.10.200.19:4873/(临时的)

  npm install @wx-sab/renkei --registry http://10.10.200.19:4873

注：可以使用 nrm 管理 npm 源

Configuration

import { GenerateApiParams, RawRouteInfo } from "swagger-typescript-api";

/**
 * 基础配置
 */
export type BasicConfig = {
  /**
   * 内置接口文档来源
   * swagger: `http://10.101.16.30:31809/${server}/v2/api-docs`
   * apifox: `http://127.0.0.1:4523/export/openapi?projectId=${projectId}&version=2.0`
   */
  sourceType?: "swagger" | "apifox";
  /**
   * 自定义接口文档来源，与 sourceType 互斥，优先级比 sourceType 高
   */
  source?: string;
  /**
   * 声明文件输出目录, 默认 src/services
   */
  output?: string;
  /**
   * 配置文件url, 默认读取项目根目录下的 renkei.config.js 或者 renkei.config.ts
   */
  configUrl?: string;
  /**
   * 数据模型的命名空间
   */
  modelNamespace?: string;
  /**
   * 接口服务名
   */
  serviceName: string;
  /**
   * 可以生成多个项目，会继承父配置项
   */
  projects?: GenerateConfig[];
  /**
   * 自定义 request 引入模板
   * 默认：import request from '${pkg.name}/lib/request'
   */
  requestTempalte?: string;
  /**
   * 自定义响应类型，默认为 AxiosResponse<T>
   */
  customResponseType?(type: string): string;
  /**
   * 自定义组装请求的url
   * 自定义组装 mock 的url
   */
  customRequestUrl?(routeData: RawRouteInfo): string | {
    /**
     * 接口请求路径
     */
    path: string;
    /**
     * mock请求完整 url
     */
    mockUrl?: string
  };
}
/**
 * 如果 sourceType 是 apifox，则适用该配置项
 */
export type ApifoxConfig = {
  /**
   * apifox 项目ID
   */
  apifoxProjectId?: string;
  /**
   * 自定义 mock 服务地址
   */
  customMockService?(config: GenerateConfig): string
};

/**
 * 配置项
 */
export type GenerateConfig = Partial<GenerateApiParams> &
  BasicConfig & ApifoxConfig;

Useage

import { defineConfig } from "@wx-sab/renkei";

export default defineConfig([
  // apifox 单服务项目
  {
    // 服务名
    serviceName: "dp-order",
    // 项目ID
    apifoxProjectId: "2963311",
  },
  // apifox 多服务项目
  {
    // 服务名
    serviceName: "dp-service",
    // 项目ID
    apifoxProjectId: "2954843",
    // 自定义 request 引入
    requestTempalte: `import { request } from '@/utils/http'`,
    // 自定义组装请求url
    customRequestUrl: (routeData) => {
      return (
        "/" +
        // @ts-ignore
        routeData["x-apifox-folder"].split("/")[0] +
        // @ts-ignore
        routeData.route
      );
    },
  },
  // swagger项目
  {
    sourceType: 'swagger',
    serviceName: 'dp-product',
  },
  // 自定义 swagger 源
  {
    source: 'https://swagger.com/xxx/xxx',
    serviceName: 'custom-swagger'
  }
]);

CLI 命令

# 生成所有服务的所有接口
renkei api

# 只生成指定服务的接口
renkei api -s dp-service

# 只生成指定文件夹的接口（命令行方式）
renkei api -f "用户管理,订单管理"

# 交互式选择要生成的文件夹
renkei api -i

# 组合使用：交互式选择指定服务的文件夹
renkei api -s dp-service -i

交互式选择文件夹

当运行 renkei api -i 时，工具会：

1. 分析每个服务的 swagger/apifox 文档
2. 提取所有文件夹信息（基于 x-apifox-folder 字段）
3. 显示交互式多选界面，默认选中"全部"选项
4. 用户可以选择：
   • 保持选中"全部"：生成所有接口
   • 取消"全部"，选择具体文件夹：只生成选中的接口

示例输出：

正在分析服务: dp-service

发现以下文件夹:
  1. 用户管理 (15 个接口)
  2. 订单管理 (23 个接口)
  3. 商品管理 (18 个接口)
  4. 支付管理 (12 个接口)

? 请选择要生成的文件夹 (空格选择，回车确认) (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◉ 全部 (共 68 个接口)
 ── 具体文件夹 ──
 ◯ 用户管理 (15 个接口)
 ◯ 订单管理 (23 个接口)
 ◯ 商品管理 (18 个接口)
 ◯ 支付管理 (12 个接口)

操作说明：

• 默认选中"全部"，生成所有接口
• 按 空格 取消"全部"，然后选择具体文件夹
• 按 a 切换全选/全不选
• 按 i 反选
• 按 回车 确认选择

文件夹过滤功能

支持三种方式指定要生成的文件夹：

1. 配置文件方式

在配置文件中通过 folders 字段指定：

import { defineConfig } from "@wx-sab/renkei";

export default defineConfig([
  {
    serviceName: "dp-service",
    apifoxProjectId: "2954843",
    // 只生成这两个文件夹的接口
    folders: ["用户管理", "订单管理"],
    customRequestUrl: (routeData) => {
      return "/" + routeData["x-apifox-folder"].split("/")[0] + routeData.route;
    },
  }
]);

2. 命令行参数方式

使用 -f 或 --folder 参数：

# 只生成指定文件夹的接口
renkei api -f "用户管理,订单管理"

# 指定服务和文件夹
renkei api -s dp-service -f "用户管理,订单管理"

3. 交互式选择方式（推荐）

使用 -i 或 --interactive 参数：

# 交互式选择所有服务的文件夹
renkei api -i

# 交互式选择指定服务的文件夹
renkei api -s dp-service -i

注意事项

1. 文件夹名称匹配：文件夹名称基于 swagger/apifox 文档中的 x-apifox-folder 字段，取第一级目录名称
2. 优先级：交互式选择 > 命令行参数 > 配置文件
3. 空数组：如果 folders 为空数组或不设置，则生成所有接口
4. 多服务：每个服务可以独立配置不同的文件夹列表

Examples

文件夹过滤示例

场景1：只生成特定模块的接口

import { defineConfig } from "@wx-sab/renkei";

export default defineConfig([
  {
    serviceName: "dp-service",
    apifoxProjectId: "2954843",
    // 只生成用户管理和订单管理模块的接口
    folders: ["用户管理", "订单管理"],
    customRequestUrl: (routeData) => {
      return "/" + routeData["x-apifox-folder"].split("/")[0] + routeData.route;
    },
  }
]);

场景2：多服务配置，每个服务过滤不同文件夹

import { defineConfig } from "@wx-sab/renkei";

export default defineConfig([
  {
    serviceName: "dp-service",
    apifoxProjectId: "2954843",
    folders: ["用户管理", "订单管理"],
    customRequestUrl: (routeData) => {
      return "/" + routeData["x-apifox-folder"].split("/")[0] + routeData.route;
    },
  },
  {
    serviceName: "cop-profile",
    apifoxProjectId: "1234567",
    folders: ["个人中心", "权限管理"],
    customRequestUrl: (routeData) => {
      return "/cop-profile" + routeData.route;
    },
  }
]);

场景3：命令行快速过滤

# 快速生成特定文件夹的接口，无需修改配置文件
renkei api -s dp-service -f "用户管理,订单管理,商品管理"

# 交互式选择，适合不确定有哪些文件夹时使用
renkei api -i

自定义接口的 mock 服务

import { request } from '@/utils/request'
import { DpService } from './services/dp-service'

const mockProxy = {
  "/dp-order": {
    mockService: "https://mock.apifox.cn/m1/2954843-0-6f0df579",
  },
  "/dp-product": {
    mockService: "https://mock.apifox.cn/m1/2954843-0-4d5b1ae0",
  },
};

generateApis({
  // 服务名
  serviceName: "dp-service",
  // 项目ID
  apifoxProjectId: "2954843",
  // 自定义 request 引入
  requestTempalte: `import request from "../../core/request";`,
  // 自定义组装请求url
  customRequestUrl: (routeData) => {
    const prefix = "/" + routeData["x-apifox-folder"].split("/")[0];
    const path = prefix + routeData.route;

    return {
      path,
      // @ts-ignore
      mockUrl: mockProxy[prefix]?.mockService ? mockProxy[prefix]?.mockService + routeData.route : undefined,
    };
  },
});