在Spring Framework 6中配置OpenAPI (Swagger) UI 3

一、核心依赖配置 #

在pom.xml中添加适配Spring Framework 6的对应依赖：

<dependencies>
    <!-- Spring Framework 核心 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webmvc</artifactId>
        <version>6.1.0</version>
    </dependency>
    <!-- OpenAPI 3 核心 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-core</artifactId>
        <version>2.2.0</version>
    </dependency>
    <!-- Swagger UI 依赖 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>2.2.0</version>
    </dependency>
    <!-- 嵌入式Jetty -->
    <dependency>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-server</artifactId>
        <version>11.0.15</version>
    </dependency>
    <dependency>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-servlet</artifactId>
        <version>11.0.15</version>
    </dependency>
</dependencies>

二、OpenAPI 配置类 #

创建配置类注册OpenAPI实例，并配置静态资源映射（解决Swagger UI页面加载失败问题）：

package com.example.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class OpenApiConfig implements WebMvcConfigurer {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("示例API文档")
                        .version("1.0")
                        .description("基于Spring Framework 6的API说明"));
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射Swagger UI的静态资源
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/springdoc/");
    }
}

三、嵌入式Jetty 启动配置 #

必须配置Jetty加载静态资源的DefaultServlet，否则Swagger UI的HTML、JS文件无法被访问：

package com.example.config;

import org.springframework.web.context.ContextLoaderListener;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
import org.springframework.web.servlet.DispatcherServlet;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.servlet.ServletHolder;

public class JettyServerConfig {

    public static void main(String[] args) throws Exception {
        Server server = new Server(8080);

        // 创建Spring上下文
        AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
        context.scan("com.example");

        // 配置Jetty Servlet上下文
        ServletContextHandler handler = new ServletContextHandler(ServletContextHandler.SESSIONS);
        handler.setContextPath("/");
        handler.addEventListener(new ContextLoaderListener(context));

        // 注册DispatcherServlet
        ServletHolder dispatcherServletHolder = new ServletHolder(new DispatcherServlet(context));
        dispatcherServletHolder.setInitOrder(1);
        handler.addServlet(dispatcherServletHolder, "/*");

        // 注册DefaultServlet处理静态资源（关键！）
        ServletHolder defaultServletHolder = new ServletHolder("default", org.eclipse.jetty.servlet.DefaultServlet.class);
        defaultServletHolder.setInitParameter("dirAllowed", "false");
        handler.addServlet(defaultServletHolder, "/");

        server.setHandler(handler);
        server.start();
        server.join();
    }
}

四、可参考的资源方向 #

GitHub仓库示例 #

找专注于Spring Framework原生（非Boot）+ 嵌入式Jetty + OpenAPI 3的仓库，核心看这几点：

• 依赖版本是否适配Spring 6
• 静态资源映射的配置细节
• Jetty上下文的Servlet注册逻辑

文章/视频内容 #

• 技术博客：重点看讲解“Spring非Boot项目配置Swagger UI”“嵌入式Jetty静态资源处理”的内容，核心解决静态资源无法加载的问题
• 视频教程：搜索“Spring Framework 6 原生项目集成OpenAPI”，关注容器配置和资源映射的实操步骤

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