Spring Boot整合Swagger3第三方类字段@Schema示例注解无效问题

第三方类字段@Schema注解不生效的解决方法 #

该问题的本质原因是：当字段类型为复杂对象时，springdoc-openapi默认会优先解析该类型自身的类结构生成Schema示例，你加在字段上的@Schema(example)配置优先级低于类型解析规则，所以会被忽略，和类是否属于第三方包没有直接关系，只是自定义类可以直接修改源码加注解，第三方类无法直接修改而已。

无需修改业务对象结构的解决方案有两种：

• 方案1：字段上直接强制指定Schema类型，不走类结构解析。修改AuthenticationC类的字段注解即可：

// Java 15+支持文本块写法，低版本把JSON转成单行转义双引号即可
@Schema(type = "object", example = """
    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "token_type": "Bearer",
        "expires_in": 7200,
        "refresh_token": "d932d10c-1a2b-3c4d-5e6f-7g8h9i0j1k2l"
    }
    """)
private org.springframework.security.oauth2.core.endpoint.OAuth2AccessTokenResponse oAuth2AccessTokenResponse;

指定type = "object"后，springdoc会直接使用你配置的example作为该字段的示例值，不再解析OAuth2AccessTokenResponse的类结构。

• 方案2：全局注册第三方类的自定义Schema，适合项目中多处用到该类的场景。新增配置类注册OpenApiCustomiser Bean即可，不需要修改业务类代码：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenApiCustomiser customerGlobalSchema() {
        return openApi -> {
            // 构造自定义的OAuth2AccessTokenResponse Schema
            Schema<?> oauth2ResponseSchema = new ObjectSchema()
                    .addProperty("access_token", new StringSchema().example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"))
                    .addProperty("token_type", new StringSchema().example("Bearer"))
                    .addProperty("expires_in", new IntegerSchema().example(7200))
                    .addProperty("refresh_token", new StringSchema().example("d932d10c-1a2b-3c4d-5e6f-7g8h9i0j1k2l"));
            // 注册到全局Schema中，所有用到该类型的地方都会复用这个自定义Schema
            openApi.getComponents().addSchemas("OAuth2AccessTokenResponse", oauth2ResponseSchema);
        };
    }
}

Jackson与Swagger(springdoc-openapi)的关联说明 #

springdoc-openapi的模型解析层默认深度集成Jackson的序列化规则，会读取Jackson的所有注解配置来生成和实际接口返回一致的Schema，核心关联逻辑如下：

• springdoc会复用Jackson的AnnotationIntrospector来扫描类和字段上的Jackson注解，比如被@JsonIgnore、@JsonIgnoreProperties标记的字段，Jackson序列化时不会输出，springdoc生成Schema时也会自动排除这些字段，保证文档和实际返回一致。
• 类似@JsonProperty("别名")、@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")、@JsonInclude(JsonInclude.Include.NON_NULL)这类Jackson注解，springdoc都会同步识别，对应调整Schema的字段名、格式、是否必填等属性。
• 默认行为优先对齐Jackson的序列化结果，核心目的是避免文档和实际接口行为不一致的问题，你也可以通过修改springdoc的配置项调整集成逻辑。

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