Springfox Swagger 3.0.0 API接口多行注释展示方案问询

直接通过Swagger注解实现的方法 #

Swagger UI默认会解析注解内容中的HTML标签，所以不用\n或\n\n，改用HTML标签即可实现多行展示：

• 用<br>实现单换行
• 用<p>标签实现带间距的段落分隔

示例代码 #

接口方法注释示例

@ApiOperation(value = "用户信息查询接口", notes = "1. 支持根据用户ID精准查询<br>" +
        "2. 若不传ID则返回所有用户列表<p>" +
        "3. 接口返回结果包含用户基础信息及关联角色数据")
@GetMapping("/users")
public ResponseEntity<List<UserVO>> queryUsers(@RequestParam(required = false) Long userId) {
    // 业务逻辑
}

请求参数注释示例

@ApiParam(value = "用户状态筛选", notes = "可选值说明：<br>" +
        "- 0: 禁用状态<br>" +
        "- 1: 正常状态<br>" +
        "- 2: 待审核状态")
@RequestParam(required = false) Integer status

其他替代方案 #

如果不想在注解中写HTML标签，可以通过自定义Swagger插件自动解析换行符：

1. 实现OperationBuilderPlugin或ParameterBuilderPlugin接口，在处理注解内容时将\n替换为<br>
2. 将自定义插件注册为Spring Bean，让Swagger加载时生效

简易自定义插件示例 #

@Component
public class SwaggerLineBreakPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        ApiOperation apiOperation = context.findAnnotation(ApiOperation.class).orElse(null);
        if (apiOperation != null && StringUtils.hasText(apiOperation.notes())) {
            String formattedNotes = apiOperation.notes().replaceAll("\\n", "<br>");
            context.operationBuilder().notes(formattedNotes);
        }
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.OAS_30.equals(documentationType);
    }
}

使用该插件后，注解中直接写\n就会自动转换为换行展示。

内容的提问来源于stack exchange，提问作者jb62