Spring Boot 3升级后Apache CXF中Swagger转OpenAPI配置问题

关键前提：依赖适配 #

首先确保使用CXF 4.x版本（适配Spring Boot 3的Jakarta EE规范），Maven依赖示例：

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-spring-boot-starter-jaxrs</artifactId>
    <version>4.0.0+</version>
</dependency>
<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
    <version>4.0.0+</version>
</dependency>
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>4.18.3</version>
</dependency>

正确的OpenAPI配置类 #

OpenAPI v3的配置逻辑和Swagger 2.x有差异，需要通过OpenApiCustomizer补充servers、contact等细节，而非直接调用OpenApiFeature的简单setter：

@Configuration
public class OpenApiConfiguration {

    @Value("${api.version}")
    private String version;

    @Value("${api.base-path}")
    private String basePath;

    @Value("${api.host}")
    private String host;

    @Value("${api.contact.name}")
    private String contactName;

    @Value("${api.contact.email}")
    private String contactEmail;

    @Value("${api.description}")
    private String description;

    @Value("${api.title}")
    private String title;

    @Bean
    public OpenApiFeature openApiFeature() {
        OpenApiFeature openApiFeature = new OpenApiFeature();
        // 基础元数据配置
        openApiFeature.setTitle(title);
        openApiFeature.setDescription(description);
        openApiFeature.setVersion(version);
        openApiFeature.setPrettyPrint(true);
        openApiFeature.setSupportSwaggerUi(true);

        // 配置Swagger UI，确保openapi.json路径正确（含basePath）
        openApiFeature.setSwaggerUiConfig(new SwaggerUiConfig()
                .url(basePath + "/openapi.json")
                .deepLinking(true)
                .displayOperationId(true));

        // 自定义OpenAPI v3核心配置（对应原Swagger2Feature的host、schemes、contact等）
        openApiFeature.getOpenApiCustomizers().add(openApi -> {
            // 配置服务地址（替代原setHost、setSchemes、setBasePath）
            Server httpsServer = new Server();
            httpsServer.setUrl("https://" + host + basePath);
            httpsServer.setDescription("HTTPS环境");

            Server httpServer = new Server();
            httpServer.setUrl("http://" + host + basePath);
            httpServer.setDescription("HTTP环境");

            openApi.setServers(List.of(httpsServer, httpServer));

            // 配置联系人信息（替代原setContact）
            Contact contact = new Contact();
            contact.setName(contactName);
            contact.setEmail(contactEmail);
            openApi.setContact(contact);
        });

        return openApiFeature;
    }
}

核心修改点说明 #

1. 服务地址配置：原Swagger2Feature的setHost、setSchemes、setBasePath被替换为Server对象集合，通过OpenApiCustomizer注入到OpenAPI实例中，符合OpenAPI v3规范。
2. 联系人信息：原setContact需要构建完整的Contact对象（包含名称和邮箱），而非仅调用setContactEmail。
3. Swagger UI路径：必须指定包含basePath的openapi.json地址，否则UI无法加载API定义文件。
4. 访问路径：Swagger UI的默认访问地址为{basePath}/swagger-ui/index.html（例如http://localhost:8080/api/swagger-ui/index.html）。

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