一、問題

• 這是一個非常煩人的錯誤，雖然我們使用了springdoc-openapi代替swagger,但是這玩意底層還是使用了它，因此在新的高版本上，就不能很好的兼容了。
  Unable to render this definition
  The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.x.y (for example, openapi: 3.1.0).

• 這也提示了，要么你降低回去使用swagger2.0，要么你就等使用3.x.y的版本。很明顯現(xiàn)在它最高版本的版本還是2.8.8版本，因此你只能放棄使用好了。

二、集成

• 集成非常的簡單，就加這個一個依賴包就可以了。

 <dependency>
        <groupId>org.springdoc</groupId>
         <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
         <version>2.8.8</version>
 </dependency>

• 接著在application.yml里面配置一下：

# swagger-ui custom path
springdoc:
  swagger-ui:
    # 修改Swagger UI路徑
    path: /swagger-ui.html
    # 開啟Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路徑
    path: /v3/api-docs
    # 開啟api-docs
    enabled: true
  # 配置需要生成接口文檔的掃描包
  packages-to-scan: com.wewetea.open.weadmin.controller
  # 配置需要生成接口文檔的接口路徑
  paths-to-match: /Users/**,/admin/**

不出意外的話，你一定會出現(xiàn)，如圖所示的問題：

image.png

三、解決

網(wǎng)上說了一堆的解決，就是檢查控制是否寫重復的問題，甚至還有點就是簡單的，告訴你下面這樣，然后你還是不會去處理。

錯誤原因：Controller 的 public 方法沒有指定 HttpMethodAttribute
解決：設(shè)置為 HttpGet 或者 HttpPost 

這些都只是小問題，是因為你自己不夠細心的導致代碼問題，和本次的真正的問題并無太多關(guān)聯(lián)。

• 【敲重點】等待一系列的問題，就是因為某個錯誤導致，他們不能反序列話讀取值。因此，我們要增加一個序列化的轉(zhuǎn)化器給過去就可以了。

package com.wewetea.open.weadmin.config;

import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.http.converter.ByteArrayHttpMessageConverter;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;

@EnableWebMvc
@Configuration
class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        List<MediaType> supportMediaTypeList = new ArrayList<>();
        supportMediaTypeList.add(MediaType.APPLICATION_JSON);
        FastJsonConfig config = new FastJsonConfig();
        config.setSerializerFeatures(SerializerFeature.DisableCircularReferenceDetect);
        converter.setFastJsonConfig(config);
        converter.setSupportedMediaTypes(supportMediaTypeList);
        converter.setDefaultCharset(StandardCharsets.UTF_8);
        converters.add(new ByteArrayHttpMessageConverter()); // 增加二進制轉(zhuǎn)換器
        converters.add(converter);
    }
}

就是這段代碼：new ByteArrayHttpMessageConverter()就可以解決問題了。
問題立馬得到解決：

image.png

{"createTime":1748613783631,"id":60,"name":"張三","updateTime":1748613783631}]

日期變成了時間戳了，但這個不是問題，因為原本它的序列化就是這樣的。后面自己寫一下自己的配置就可以解決了。配置參考：

package com.wewetea.open.weadmin.config;

import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;

import java.util.Arrays;

@Configuration
class FastJsonConverterConfig {
    @Value("${spring.jackson.date-format:yyyy-MM-dd HH:mm:ss}")
    private String pattern;

    @Value("${spring.jackson.time-zone:GMT+8}")
    private String zone;

    @Bean
    public HttpMessageConverters fastJsonHttpMessageConverters() {
        FastJsonHttpMessageConverter fastConverter = new FastJsonHttpMessageConverter();
        FastJsonConfig fastJsonConfig = new FastJsonConfig();
        fastJsonConfig.setSerializerFeatures(
                SerializerFeature.WriteMapNullValue,
                SerializerFeature.WriteNullListAsEmpty,
                SerializerFeature.WriteNullStringAsEmpty,
                SerializerFeature.WriteNullBooleanAsFalse,
                SerializerFeature.WriteDateUseDateFormat
        );
        fastConverter.setFastJsonConfig(fastJsonConfig);

        // 全局指定了日期格式
        fastJsonConfig.setDateFormat(pattern);

        // 該設(shè)置目的，為了兼容jackson
        fastConverter.setSupportedMediaTypes(Arrays.asList(MediaType.APPLICATION_JSON,MediaType.APPLICATION_JSON_UTF8,MediaType.APPLICATION_OCTET_STREAM));
        return new HttpMessageConverters(fastConverter);
    }
}

把兩者結(jié)合起來，就能解決整體的問題了。最后給出完整的處理代碼：

package com.wewetea.open.weadmin;

import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.http.converter.ByteArrayHttpMessageConverter;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.nio.charset.StandardCharsets;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.List;
import java.util.TimeZone;

@EnableWebMvc
@Configuration
class WebMvcConfig implements WebMvcConfigurer {
    @Value("${spring.jackson.date-format:yyyy-MM-dd HH:mm:ss}")
    private String pattern;

    @Value("${spring.jackson.time-zone:GMT+8}")
    private String zone;

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();

        List<MediaType> supportMediaTypeList = new ArrayList<>();
        supportMediaTypeList.add(MediaType.APPLICATION_JSON);
        supportMediaTypeList.add(MediaType.APPLICATION_ATOM_XML);
        supportMediaTypeList.add(MediaType.APPLICATION_FORM_URLENCODED);
        supportMediaTypeList.add(MediaType.APPLICATION_OCTET_STREAM);

        FastJsonConfig config = new FastJsonConfig();
        config.setSerializerFeatures(SerializerFeature.DisableCircularReferenceDetect);

        // 統(tǒng)一處理時區(qū)和時間格式
        SimpleDateFormat dateFormat = new SimpleDateFormat(pattern);
        dateFormat.setTimeZone(TimeZone.getTimeZone(zone));
        // 全局指定了日期格式
        config.setDateFormat(dateFormat.toPattern());

        converter.setFastJsonConfig(config);
        converter.setSupportedMediaTypes(supportMediaTypeList);
        converter.setDefaultCharset(StandardCharsets.UTF_8);

        // 增加二進制轉(zhuǎn)換器,解決Spring doc的問題。
        converters.add(new ByteArrayHttpMessageConverter());
        converters.add(converter);
    }
}

• 配置如下，在application.yml里面配置一下：

spring:
  # 統(tǒng)一編碼
  jackson:
    time-zone: GMT+8
    date-format: yyyy-MM-dd HH:mm:ss

至此，所有問題都可以得到解決。