普通Spring项目将Swagger2升级至Swagger3的配置类修改问题咨询

需要调整的核心修改点 #

• 删除类上的@EnableSwagger2注解，替换为 springdoc 提供的@OpenAPIDefinition注解即可
• 移除所有 springfox 相关的依赖导入，替换为 springdoc 和 swagger3 对应的类导入
• 原有Docket类型的Bean拆分为两个配置Bean：GroupedOpenApi负责接口扫描、分组规则配置，OpenAPI负责全局文档基础信息配置
• 原有包扫描、路径匹配的逻辑保持不变，仅需替换对应的工具类包路径
• Spring Boot 版本适配说明：Spring Boot 3.x 需使用 2.x 以上版本的springdoc-openapi-starter-webmvc-ui依赖，Spring Boot 2.x 对应使用 1.x 版本的 springdoc-openapi 依赖

修改完成后的完整配置代码 #

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springdoc.core.predicates.PathSelectors;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;

@Configuration
@OpenAPIDefinition
public class SwaggerConfiguration {

    // 接口扫描、分组规则配置
    @Bean
    public GroupedOpenApi api() {
        return GroupedOpenApi.builder()
                .group("默认分组")
                .pathsToMatch(PathSelectors.any())
                .packagesToScan("com.hjk.controller")
                .build();
    }

    // 全局文档信息配置，对应原有ApiInfo的配置
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(title)
                        .description(description)
                        .version(version)
                        .termsOfService(termsOfServiceUrl)
                        .contact(new Contact()
                                .name(contact.getName())
                                .url(contact.getUrl())
                                .email(contact.getEmail())
                        )
                        .license(new License()
                                .name(license)
                                .url(licenseUrl)
                        )
                );
    }
}

额外注意事项 #

升级后Swagger UI的默认访问地址从原来的http://服务地址/swagger-ui.html变更为http://服务地址/swagger-ui/index.html

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