如何在OpenAPI Generator中仅生成TypeScript类型定义

在使用OpenAPI Generator工具时，开发者有时只需要生成TypeScript的类型定义，而不需要生成API相关的控制器和资源代码。本文将详细介绍如何实现这一目标。

问题背景

OpenAPI Generator是一个强大的工具，能够根据Swagger/OpenAPI规范自动生成客户端和服务端代码。默认情况下，它会生成完整的API客户端代码，包括类型定义、API调用方法和相关工具类。但在某些场景下，开发者可能只需要类型定义部分。

解决方案

方法一：使用忽略文件

最有效的方式是使用.openapi-generator-ignore文件来控制生成的内容。这个文件的工作方式类似于.gitignore，可以指定哪些文件不应该被生成。

1. 在项目根目录下创建.openapi-generator-ignore文件
2. 添加以下内容：

   **/api/**
   **/*Api.ts
   **/*Api.js
   **/*Api.*.ts
   **/*Api.*.js
   

这样配置后，生成器会跳过所有API相关的文件，只保留模型定义文件。

方法二：配置生成器参数

虽然直接配置生成器参数看起来更直观，但目前OpenAPI Generator的TypeScript生成器并没有提供完全禁用API生成的选项。即使设置了generateApis: false等参数，某些基础API代码仍会被生成。

最佳实践建议

1. 保持生成器版本最新：使用最新稳定版本（当前为7.11.0）可以获得最好的功能和稳定性。

2. 结合两种方法：同时使用.openapi-generator-ignore文件和配置参数可以获得最可靠的结果。

3. 明确输出目录结构：建议将生成的代码放在专门的目录中（如src/generated），便于管理和版本控制。

4. 类型定义优化：可以通过以下参数优化生成的类型定义：

   • stringEnums: true - 生成字符串枚举
   • withInterfaces: true - 生成接口定义
   • modelPropertyNaming: "original" - 保持属性名与规范一致

总结

虽然OpenAPI Generator主要设计用于生成完整的API客户端代码，但通过合理使用忽略文件和配置参数，开发者可以有效地仅提取所需的类型定义部分。这种方法特别适用于前端项目或需要与现有API客户端集成的场景。