JAX-RS集成Swagger-Core时，如何修改自动生成的OpenAPI模型并替换原对象以补全缺失的响应描述

我刚好碰到过几乎一模一样的场景，Swagger Core其实提供了专门的扩展点来解决这个问题——OpenApiCustomizer接口，完全符合你要的「模型构建完成后、缓存/序列化前只修改一次」的需求，而且不会有你说的反射性能问题。

具体实现步骤： #

1. 实现OpenApiCustomizer接口，封装你的补全逻辑

把你已经写好的patchMissingDescriptions方法逻辑放到这个自定义器里：

import io.swagger.v3.core.util.OpenApiCustomizer;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.responses.ApiResponse;
import java.util.Map;

public class MissingDescriptionCustomizer implements OpenApiCustomizer {
    @Override
    public void customize(OpenAPI openAPI) {
        if (openAPI.getPaths() == null) {
            return;
        }
        
        for (Map.Entry<String, PathItem> pathEntry : openAPI.getPaths().entrySet()) {
            for (Operation operation : pathEntry.getValue().readOperations()) {
                if (operation.getResponses() == null) {
                    continue;
                }
                
                for (Map.Entry<String, ApiResponse> respEntry : operation.getResponses().entrySet()) {
                    ApiResponse response = respEntry.getValue();
                    if (response.getDescription() == null || response.getDescription().trim().isEmpty()) {
                        // 这里可以根据状态码设置更精准的描述
                        String statusCode = respEntry.getKey();
                        switch (statusCode) {
                            case "200":
                                response.setDescription("请求成功，返回预期结果");
                                break;
                            case "201":
                                response.setDescription("资源创建成功");
                                break;
                            case "400":
                                response.setDescription("请求参数不合法，请检查输入");
                                break;
                            case "401":
                                response.setDescription("未授权，请先登录");
                                break;
                            case "403":
                                response.setDescription("无权限访问该资源");
                                break;
                            case "404":
                                response.setDescription("请求的资源不存在");
                                break;
                            case "500":
                                response.setDescription("服务器内部错误，请稍后重试");
                                break;
                            default:
                                response.setDescription("请求处理完成");
                        }
                    }
                }
            }
        }
    }
}

2. 在Swagger配置中注册这个自定义器

修改你原来的SwaggerConfiguration构建代码，把自定义器加进去：

SwaggerConfiguration oasConfig = new SwaggerConfiguration()
        .openApi(baseModel)
        .prettyPrint(true)
        .resourcePackages(Set.of("my.api.package"))
        .addCustomizer(new MissingDescriptionCustomizer()); // 关键：注册自定义器

3. 保持原有上下文构建代码不变

你原来的JaxrsOpenApiContextBuilder代码不需要修改：

OpenApiContext openApiCtx = new JaxrsOpenApiContextBuilder()
        .openApiConfiguration(oasConfig)
        .buildContext(true);

为什么这个方案可行？ #

• 执行时机精准：Swagger Core会在OpenAPI模型第一次构建完成后、缓存到上下文之前，自动调用所有注册的OpenApiCustomizer的customize方法，而且只会执行一次，完全避免了重复扫描的性能问题。
• 修改生效在序列化前：和你尝试的ContainerResponseFilter不同，这个修改是在模型序列化之前完成的，所以返回给Swagger UI的JSON/YAML已经是补全后的完整模型，不会再出现「missingProperty: description」的报错。
• 扩展性强：除了补全响应描述，你还可以在这个自定义器里做其他模型修改，比如统一添加全局响应头、调整标签排序等。

注意事项 #

确保你的Swagger Core版本是3.0.0及以上，OpenApiCustomizer接口是在这个版本之后引入的，如果版本过低需要先升级依赖。

内容来源于stack exchange