springboot3探索日记（2）——knife4j升级

springboot版本：3.2.0

jdk版本：21

knife4j-openapi3-jakarta-spring-boot-starter：4.3.0

maven依赖：

    <!--版本管理-->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>3.2.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>        
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.3.0</version>
        </dependency>
    </dependencies>  

我升级前是jdk8，springboot2.7.13，knife4j-spring-boot-starter：3.0.3

升级后，首先knife4j的配置就报错了。先改配置：

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("demo接口文档")
                        .version("0.0.1")
                        .description("demo 接口文档(springboot3)")
                        .contact(new Contact()
                                .name("七维空间")
                                .email("xxxx@163.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("[七维空间]接口文档"));
    }

    // 配置文档分组1
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("default")
                .pathsToMatch("/**")
                .build();
    }
    // 配置文档分组2......可以配置多个分组
//    @Bean
//    public GroupedOpenApi specificationsApi(){
//        return GroupedOpenApi.builder()
//                .displayName("开发规范")
//                .group("default")
//                .pathsToMatch("markdown/**")
//                .build();
//    }

}

application.yml，可以加载自定义的文档，我这里设置了一下markdown格式的项目说明

#接口文档
knife4j:
  enable: true
  basic:
    enable: false
    username: admin
    password: 123!@3$
  # 自定义文档加载
  documents:
    - name: 项目说明
      locations: classpath:markdown/*
      group: default

资源映射+序列化支持

重点来了，有一个坑一定要注意，如果你的项目中继承重写了WebMvcConfigurer，那一定要加一个ByteArrayHttpMessageConverter这个转换器，这也是找遍官网，在某角落的大神回复中找到的。因为就实际项目中来说，一般这个类都是会重写的。

@Configuration
public class WebDataConvertConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 解决swagger3响应问题
        converters.add(new ByteArrayHttpMessageConverter());
        // json序列化
        converters.add(jackson2HttpMessageConverter());
        // xml序列化
        XmlMapper xmlMapper = new XmlMapper.Builder(new XmlMapper())
                .enable(ToXmlGenerator.Feature.WRITE_XML_DECLARATION)
                .defaultUseWrapper(false)
                .build();
        MappingJackson2XmlHttpMessageConverter mxlConverter = new MappingJackson2XmlHttpMessageConverter(xmlMapper);
        converters.add(mxlConverter);


    }

    @Bean
    public MappingJackson2HttpMessageConverter jackson2HttpMessageConverter() {
        MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
        ObjectMapper objectMapper = new ObjectMapper();
        //反序列化的时候如果多了其他属性,不抛出异常
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        SimpleModule simpleModule = new SimpleModule();
        //序列化 :序列换成json时,将所有的long变成string(防丢精度)
        simpleModule.addSerializer(Long.class, ToStringSerializer.instance);
        simpleModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
        simpleModule.addSerializer(LocalDateTime.class, new LocalDateTimeSerialize.SecondsSerializer());
        simpleModule.addSerializer(LocalDate.class, new LocalDateSerializer());
        simpleModule.addSerializer(LocalTime.class, new LocalTimeSerialize());
        //反序列化
        simpleModule.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer());
        simpleModule.addDeserializer(LocalDate.class, new LocalDateDeserializer());
        simpleModule.addDeserializer(LocalTime.class, new LocalTimeDeserializer());
        objectMapper.registerModule(simpleModule);
        jackson2HttpMessageConverter.setObjectMapper(objectMapper);

        return jackson2HttpMessageConverter;
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // swagger配置
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

剩下的就是把之前的swagger注解升级一下，得用swagger3的注解，swagger2的好多注解都已经删除掉啦，想用也用不了。新的注解：

@Tag	用在controller类上，描述此controller的信息
@Operation	用在controller的方法里，描述此api的信息
@Parameter	用在controller方法里的参数上，描述参数信息
@Parameters	用在controller方法里的参数上
@Schema	用于Entity，以及Entity的属性上
@ApiResponse	用在controller方法的返回值上
@ApiResponses	用在controller方法的返回值上
@Hidden	用在各种地方，用于隐藏其api
@ApiSupport	用的ctroller类，排序ctroller顺序，注解没变
@ApiOperationSupport	用在ctoller中接口上，排序接口，注解没变

把所有注解替换成新的就ok了

@Data
@Schema(description = "demo实体")
public class DemoEntity implements Serializable {
    @Serial
    private static final long serialVersionUID = -5237988195804658173L;

    @Schema(description = "id")
    private Long id;

    @Schema(description =  "姓名")
    private String name;

    @Schema(description =  "性别(0,男 1,女)")
    private Integer sex;
}

@RestController
@RequestMapping("/mybatis-demo")
@Tag(name = "示例")
public class MpDemoController {

    @Resource
    private MpDemoService oneService;

    @PostMapping("/add")
    @Operation(summary = "新增")
    @ApiOperationSupport(order = 1)
    public Resp<Void> add(@Valid @RequestBody DemoEntity oneEntity) {
        boolean insert = oneService.save(oneEntity);
        return Resp.success();
    }

}