Spring Boot生成Swagger定义报错：example与examples互斥

问题本质 #

你遇到的错误是因为OpenAPI规范明确要求example和examples字段互斥，但生成的Swagger定义中同时出现了配置好的examples（来自注解的示例数据）和框架默认生成的example: null，导致语法校验失败。

解决方案 #

1. 全局禁用默认空示例（推荐）

如果你使用SpringDoc作为Swagger3的实现库，直接在配置文件中添加参数，阻止框架自动生成空的example字段：

• application.properties：

springdoc.api-docs.default-request-example-enabled=false

• application.yml：

springdoc:
  api-docs:
    default-request-example-enabled: false

2. 显式指定Schema避免默认生成

调整Swagger注解，在@Content中显式声明Schema实现类，可能会阻止框架自动添加空example：

public ResponseEntity<PromotionsDTO> getPromotions(
        @Parameter(name = "requestBody", description = "requestBody") @Valid
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
                required = true, 
                content = @Content(
                        schema = @Schema(implementation = PromotionsRequestBody.class),
                        examples = { @ExampleObject(name = "promotionsRequestBody", value = Constants.PROMOTIONS_REQUEST_EXAMPLE) }
                )
        ) 
        @RequestBody PromotionsRequestBody requestBody)
{
    // 方法逻辑
}

3. 自定义OpenAPI处理器移除冗余字段

如果以上方法无效，可以实现OpenApiCustomizer，在生成Swagger定义时手动移除多余的example字段：

import org.springdoc.core.customizers.OpenApiCustomizer;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.parameters.RequestBody;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenApiCustomizer removeNullExampleCustomizer() {
        return openApi -> {
            openApi.getPaths().values().forEach(pathItem -> {
                pathItem.readOperations().forEach(operation -> {
                    RequestBody requestBody = operation.getRequestBody();
                    if (requestBody != null && requestBody.getContent() != null) {
                        requestBody.getContent().values().forEach(content -> content.setExample(null));
                    }
                });
            });
        };
    }
}

验证方法 #

修改配置/代码后重新生成Swagger定义，在Swagger编辑器中检查，确认example: null已被移除，错误提示消失即可。

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