SpringBoot项目中接口Optional类型字段如何在Swagger中正确传值

错误示例的产生原因 #

你在Swagger页面看到的包含empty、present字段的结构是错误的，这是因为默认配置下，Jackson没有启用JDK8 Optional类型的专门处理逻辑，Swagger把Optional当成普通Java对象解析，识别到它内置的isEmpty()、isPresent() getter方法，就误将这两个属性当成了请求字段生成示例。

临时测试传参方法 #

如果你仅需要临时测试接口，不需要调整代码，直接忽略Swagger生成的错误示例即可，按照以下规则传参就能正常被后端解析：

• 要给alive传有效值：直接将字段值设为你需要的字符串即可，示例：

  "alive": "YES"
  

  后端接收到的就是Optional.of("YES")
• 要让alive为空：要么不传这个字段，要么将值设为null，后端接收到的就是Optional.empty()

永久修复Swagger示例错误方案 #

如果要让Swagger生成正确的请求示例，避免其他使用接口的人困惑，可以做以下配置：

1. 确保引入Jackson JDK8类型处理模块
   SpringBoot 2.x及以上版本默认已经集成jackson-datatype-jdk8，不需要额外引入；低版本可以在pom中添加依赖：

   <dependency>
       <groupId>com.fasterxml.jackson.datatype</groupId>
       <artifactId>jackson-datatype-jdk8</artifactId>
   </dependency>
   

2. 配置Swagger识别Optional类型
   如果你使用的是SpringDoc OpenAPI 3，可以添加如下配置类，让Swagger自动识别Optional包裹的实际类型生成示例：

   import io.swagger.v3.core.converter.AnnotatedType;
   import io.swagger.v3.core.converter.ModelConverter;
   import io.swagger.v3.core.converter.ModelConverterContext;
   import io.swagger.v3.oas.models.media.Schema;
   import org.springdoc.core.converters.SchemaPropertyDeprecatingConverter;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import java.util.Iterator;
   import java.util.Optional;
   
   @Configuration
   public class SwaggerOptionalConfig {
   
       @Bean
       public ModelConverter optionalSchemaConverter() {
           return new SchemaPropertyDeprecatingConverter() {
               @Override
               public Schema<?> resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
                   if (Optional.class.isAssignableFrom((Class<?>) type.getType())) {
                       // 提取Optional包裹的实际泛型类型
                       Class<?> actualType = com.fasterxml.jackson.databind.type.TypeFactory.defaultInstance()
                               .constructType(type.getType()).containedType(0).getRawClass();
                       return context.resolve(new AnnotatedType(actualType));
                   }
                   return super.resolve(type, context, chain);
               }
           };
       }
   }
   

   配置完成后重启应用，Swagger生成的请求示例中alive字段就会显示为正确的"alive": "string"格式。

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