lx-swagger-cli

一个强大的 API 代码生成工具，支持从 Swagger/OpenAPI 文档自动生成 TypeScript API 函数。

特性

• 🚀 支持 Swagger/OpenAPI 3.x 平台
• 📁 智能的URL层级分组和目录结构
• 🎯 简洁的函数命名策略（基于URL路径最后两个部分）
• 📝 自动生成完整的 TypeScript 类型定义和接口
• 💬 智能字段注释：从API响应schema自动提取字段描述生成JSDoc注释
• 🔗 URL优化：自动移除API前缀，保持目录结构的同时简化请求URL
• 🔧 零配置快速上手
• 📂 每个资源生成到独立目录，文件名为 index.ts

安装

npm install -g lx-swagger-cli

使用方法

快速开始

# 生成 TypeScript API 函数
swagger

首次运行会引导您输入Swagger API文档URL并创建配置文件。

配置文件示例

创建/修改 api-gen.config.json：

{
  "platform": "swagger",
  "baseUrl": "http://your-api-server.com/api-docs"
}

配置参数

• platform: API平台类型（固定为 swagger）
• baseUrl: Swagger API文档地址

生成的代码示例

TypeScript API 函数

工具会根据URL层级智能分组，生成简洁的函数名（基于URL路径最后两个部分），并自动从API响应schema中提取字段注释：

import request from "@/config/axios"

export interface PageParam {
  pageNo: number
  pageSize: number
}

/** 管理后台 - 租户 Response VO */
export interface TenantVO {
  /** 租户编号 */
  id: number
  /** 租户名 */
  name: string
  /** 联系人 */
  contactName: string
  /** 联系手机 */
  contactMobile: string
  /** 租户状态 */
  status: number
  /** 绑定域名 */
  website: string
  /** 租户套餐编号 */
  packageId: number
  /** 用户账号 */
  username: string
  /** 密码 */
  password: string
  /** 过期时间 */
  expireTime: Date
  /** 账号数量 */
  accountCount: number
  /** 创建时间 */
  createTime: Date
}

export interface TenantPageReqVO extends PageParam {
  /** 租户名 */
  name?: string
  /** 联系人 */
  contactName?: string
  /** 联系手机 */
  contactMobile?: string
  /** 租户状态（0正常 1停用） */
  status?: number
  /** 创建时间 */
  createTime?: Date[]
}

// 查询租户列表 - 基于 /tenant/page
export const tenantPage = (params: TenantPageReqVO) => {
  return request.get({ url: "/system/tenant/page", params })
}

// 查询租户详情 - 基于 /tenant/get
export const tenantGet = (id: number) => {
  return request.get({ url: "/system/tenant/get?id=" + id })
}

// 新增租户 - 基于 /tenant/create
export const tenantCreate = (data: TenantVO) => {
  return request.post({ url: "/system/tenant/create", data })
}

// 修改租户 - 基于 /tenant/update
export const tenantUpdate = (data: TenantVO) => {
  return request.put({ url: "/system/tenant/update", data })
}

// 删除租户 - 基于 /tenant/delete
export const tenantDelete = (id: number) => {
  return request.delete({ url: "/system/tenant/delete?id=" + id })
}

// 批量删除租户 - 基于 /tenant/delete-list
export const tenantDeleteList = (ids: number[]) => {
  return request.delete({
    url: "/system/tenant/delete-list",
    params: { ids: ids.join(",") }
  })
}

命名规则

核心原则：基于URL路径的最后两个部分组合生成函数名

函数名生成规则

• 格式：{倒数第二层}{最后一层}（驼峰命名法）
• 示例：
  • /admin-api/system/tenant/page → tenantPage
  • /admin-api/system/tenant/create → tenantCreate
  • /admin-api/system/tenant/delete-list → tenantDeleteList
  • /admin-api/system/user/profile → userProfile

目录结构

• 每个资源生成到独立目录
• 文件名固定为 index.ts
• 保持完整的URL层级结构

更新日志

v2.3.0

• 💬 新增功能：智能字段注释生成
• 📝 从API响应schema自动提取字段描述，生成JSDoc注释
• 🎯 优先从GET接口响应中提取实体结构，确保注释准确性
• 🔧 优化URL生成逻辑，自动移除API前缀（admin-api、app-api等）
• ✨ 支持接口级和字段级注释，提升代码可读性

v2.2.0

• 🚀 重大更新：专注于 Swagger/OpenAPI 平台
• 📝 移除JavaScript生成，只生成TypeScript文件
• 🎯 简化CLI命令，移除 -t 参数，直接执行 swagger 即可
• 📁 优化目录结构，移除 typescript 子目录
• ✨ 新的函数命名规则：基于URL路径最后两个部分组合
• 📂 每个资源生成到独立目录，文件名为 index.ts
• 🔧 大幅简化代码，移除JavaScript生成相关逻辑

v2.1.1

• 🎯 重大改进：函数命名规则优化，HTTP方法前置
• ✨ 支持驼峰命名法，连字符和下划线自动转换
• 🔧 解决不同URL模式下的函数名冲突问题
• 📝 完善命名规则文档，增加详细说明和示例

v2.1.0

• 🔧 修复URL层级分组逻辑，保持完整的URL层级结构
• 📁 去掉 function 目录，直接输出到 api-gen/
• 🎯 优化函数命名：倒数第二层作为文件名，最后一层作为函数名
• ✨ 支持APIPost和Swagger的统一分组逻辑
• 📝 更新README文档，修正命名规则说明

许可证

MIT

作者

kevin