OpenAPI to TypeScript Generator

将 OpenAPI/Swagger 规范转换为 TypeScript 接口和服务类。

功能

• 支持 OpenAPI 3.0 和 Swagger 2.0
• 生成 TypeScript 接口定义
• 生成请求服务类
• 支持 Mock 数据生成
• 支持自定义请求库
• 支持自定义命名和类型转换

使用方法

npm install @thunder_ai/openapi

在项目根目录新建 openapi2ts.config.ts 或者 .openapi2tsrc.ts

配置文件还支持 openapi2ts.config.ts, .openapi2tsrc.json 等格式，参考 cosmiconfig

export default {
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './servers'
}

如果单个项目有多个生成需求，支持传入数组配置

export default [
  {
    schemaPath: 'http://app.swagger.io/v2/swagger.json',
    serversPath: './servers/app'
  },
  {
    schemaPath: 'http://auth.swagger.io/v2/swagger.json',
    serversPath: './servers/auth'
  }
]

在 package.json 的 script 中添加 api: "openapi2ts": "openapi2ts",

生成api

npm run openapi2ts

参数

| 属性 | 必填 | 备注 | 类型 | 默认值 | | ---------------------- | ---- | --------------------------------- | --------------------------- | -------------------- | | requestLibPath | 否 | 自定义请求方法路径 | string | - | | requestOptionsType | 否 | 自定义请求方法 options 参数类型 | string | {[key: string]: any} | | requestImportStatement | 否 | 自定义请求方法表达式 | string | - | | apiPrefix | 否 | api 的前缀 | string | - | | serversPath | 否 | 生成的文件夹的路径 | string | - | | schemaPath | 否 | Swagger 2.0 或 OpenAPI 3.0 的地址 | string | - | | projectName | 否 | 项目名称 | string | - | | authorization | 否 | 文档登录凭证 | string | - | | namespace | 否 | 命名空间名称 | string | API | | mockFolder | 否 | mock目录 | string | - | | enumStyle | 否 | 枚举样式 | string-literal | enum | string-literal | | nullable | 否 | 使用null代替可选 | boolean | false | | dataFields | 否 | response中数据字段 | string[] | - | | isCamelCase | 否 | 小驼峰命名文件和请求函数 | boolean | true | | hook | 否 | 自定义 hook | Custom Hook | - |

Custom Hook

| 属性 | 类型 | 说明 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | - | | customFunctionName | (data: APIDataType) => string | 自定义请求方法函数名称 | | customTypeName | (data: APIDataType) => string | 自定义类型名称 | | customClassName | (tagName: string) => string | 自定义类名 | | customType | (schemaObject: SchemaObject | undefined,namespace: string,originGetType:(schemaObject: SchemaObject | undefined, namespace: string) => string,) => string | 自定义获取类型 返回非字符串将使用默认方法获取type | | customFileNames | (operationObject: OperationObject,apiPath: string,_apiMethod: string,) => string[] | 自定义生成文件名，可返回多个，表示生成多个文件. 返回为空，则使用默认的获取方法获取 |

使用示例

基础用法

// openapi2ts.config.ts
export default {
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './src/services',
  projectName: 'petstore'
}

自定义请求库

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  requestLibPath: '@/utils/request',
  requestImportStatement: `import request from '@/utils/request'`
}

自定义API前缀

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  apiPrefix: '/api/v1',
  // 或者使用函数动态设置
  apiPrefix: ({ path, method, namespace }) => {
    if (path.startsWith('/auth')) {
      return '/api/v2'
    }
    return '/api/v1'
  }
}

生成Mock数据

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  mockFolder: './mock'
}

自定义类型转换

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  hook: {
    customType: (schemaObject, namespace, originGetType) => {
      // 将number类型转为string
      if (schemaObject?.type === 'number') {
        return 'string'
      }
      // 其他情况使用默认转换
      return originGetType(schemaObject, namespace)
    }
  }
}

自定义文件名生成

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  hook: {
    customFileNames: (operationObject, apiPath, apiMethod) => {
      // 根据operationId生成文件名
      const { operationId } = operationObject
      if (!operationId) return []
      return [operationId.split('_')[0]]
    }
  }
}

带认证的API文档

export default {
  schemaPath: 'https://api.example.com/swagger.json',
  serversPath: './src/services',
  authorization: 'Bearer your-token-here'
}

完整配置示例

export default {
  schemaPath: './swagger.json',
  serversPath: './src/services',
  projectName: 'myapi',
  requestLibPath: '@/utils/request',
  namespace: 'API',
  apiPrefix: '/api/v1',
  mockFolder: './mock',
  enumStyle: 'enum',
  nullable: true,
  isCamelCase: true,
  dataFields: ['data', 'result'],
  hook: {
    customFunctionName: (data) => `request${data.functionName}`,
    customTypeName: (data) => `I${data.typeName}`,
    customClassName: (tagName) => `${tagName}Service`
  }
}