OpenAPI Generator Spring生成枚举注释丢失换行问题求助

算力阿峰

2026-8-13

解决OpenAPI Generator 5.3.0 Spring枚举注释换行丢失问题

问题重现

YAML枚举定义使用块标量（|）保留换行：

type: string
description: |
  ### random text
  
  random text in new line

生成的Java枚举注释换行被合并：

/**
 * ### random text  random text in new line
 */
public enum UsageType {

手动添加硬换行
在YAML的description行末尾添加两个空格再换行，强制生成器识别换行：
```
type: string
description: |
  ### random text  
  random text in new line
```
生成的注释会保留换行结构。
自定义Freemarker模板
找到Spring生成器的enum.mustache模板文件，修改注释生成逻辑，将Markdown换行转换为Java注释的换行。例如把模板中渲染description的部分：
```
/**
 * {{{description}}}
 */
```
修改为：
```
/**
 * {{description?replace("\n", "\n * ")}}
 */
```
这样能主动将换行符转换为Java注释的换行格式。
升级OpenAPI Generator版本
5.3.0版本存在Markdown注释换行处理的Bug，升级至6.x及以上版本后，块标量定义的换行可直接被保留，无需额外配置。