Swagger @Schema注解描述中换行符\n在Swagger UI模型文档中失效的解决方法咨询

API 探路者

2026-4-29

好的，我来帮你解决这个问题。Swagger UI默认会把@Schema描述里的纯文本换行符\n忽略掉——毕竟HTML渲染时不会将普通换行识别为换行。要实现多行展示，有两种简单有效的方法：

方法1：使用HTML `<br>` 标签替换换行符

直接把描述里的\n换成<br>，Swagger UI原生支持解析HTML标签，这样就能直接实现换行效果。修改后的代码如下：

@Schema(description = "Lorem ipsum dolor sit amet<br> consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua<br> Ut enim ad minim veniam<br> quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat")
@StringField(required = false)
private String myField;

方法2：利用Markdown换行规则（适用于新版Swagger UI）

新版本的Swagger UI默认支持Markdown渲染，Markdown里的换行需要在每行末尾加两个空格再换行。你可以在@Schema的描述字符串里，给每个\n前面补上两个空格：

@Schema(description = "Lorem ipsum dolor sit amet  \n consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua  \n Ut enim ad minim veniam  \n quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat")
@StringField(required = false)
private String myField;