快捷導(dǎo)航

springboot3.x集成SpringDoc Swagger3過(guò)程

更新時(shí)間：2026年01月04日 08:37:52 作者：咚咚陽(yáng)丶

文章介紹了如何將Spring Boot 2.x升級(jí)到3.x并同步升級(jí)Swagger 2到Swagger 3,包括添加Maven依賴、編寫SpringDoc配置類、添加Swagger 3注解、自定義過(guò)濾器防止未授權(quán)訪問(wèn)等步驟

一、添加maven依賴

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

二、編寫SpringDoc配置類

/**
 * spring doc配置
 */
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI restfulOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("springboot3.x demo")
                        .description("Spring Boot3 Restful API")
                        .version("V1.0.0")
                        .license(new License().name("訪問(wèn)SpringDoc官方網(wǎng)站").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("歡迎訪問(wèn)LDY的技術(shù)博客")
                        .url("https://blog.csdn.net/ldy1016"));
    }

}

啟動(dòng)項(xiàng)目，在瀏覽器輸入{ip}:{端口}/swagger-ui/index.html，查看效果，如127.0.0.1:8080/swagger-ui/index.html

三、添加swagger3注解

首先來(lái)看一下swagger2和swagger3中注解的對(duì)應(yīng)關(guān)系，方便使用swagger2的同學(xué)升級(jí)到swagger3

swagger2	swagger3	說(shuō)明
@Api	@Tag	用在請(qǐng)求的類上，表示對(duì)類的說(shuō)明
@ApiIgnore	@Hidden	隱藏顯示
@ApiImplicitParam	@Parameter	用在請(qǐng)求方法上，指定具體某一個(gè)請(qǐng)求參數(shù)的詳細(xì)信息
@ApiImplicitParams	@Parameters	用在請(qǐng)求方法上，表示一組參數(shù)的說(shuō)明
@ApiModel	@Schema	用于請(qǐng)求或者響應(yīng)類上，說(shuō)明請(qǐng)求或者響應(yīng)數(shù)據(jù)
@ApiModelProperty	@Schema	用在屬性上，描述響應(yīng)類的屬性用，swagger2中的hidden = true屬性相當(dāng)于swagger3中的accessMode = READ_ONLY屬性
@ApiOperation	@Operation	用在請(qǐng)求的方法上，說(shuō)明方法的用途、作用，對(duì)應(yīng)注解中swagger2中的value和notes屬性對(duì)應(yīng)swagger3中的summary和description屬性
@ApiParam	@Parameter	描述參數(shù)信息

參考示例：

@Tag 描述整個(gè)類

@Tag(name = "用戶管理")
@RestController
@RequestMapping("/user")
public class UserController {}

@Operation 用在請(qǐng)求的方法上，說(shuō)明方法的用途、作用

    @Operation(summary = "查詢用戶列表接口",description = "部門用戶信息")
    @GetMapping("/list")
    public List<UserVO> list(@RequestBody UserQueryParam param) {

        //TODO 查詢用戶信息并返回

        return null;
    }

@Schema 用于請(qǐng)求或者響應(yīng)類上，說(shuō)明請(qǐng)求或者響應(yīng)數(shù)據(jù)，用在屬性上，描述響應(yīng)類的屬性用

@Data
@Schema(title = "用戶信息查詢參數(shù)")
public class UserQueryParam implements Serializable {
    private static final long serialVersionUID = 4159622041608936674L;

    @Schema(title = "部門")
    private String department;

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

    @Schema(title = "性別",allowableValues = "0,1",example = "0")
    private Integer sex;

}

打開swagger頁(yè)面查看效果

四、自定義過(guò)濾器，防止swagger文檔未授權(quán)訪問(wèn)

swagger3未授權(quán)訪問(wèn)的路徑主要包括/v3/api-docs和/swagger-ui/index.html。

本人提供的解決方案就是通過(guò)過(guò)濾器的方式對(duì)請(qǐng)求進(jìn)行驗(yàn)證，請(qǐng)求的時(shí)候需要在鏈接后面加上我們自定義的token參數(shù)，通過(guò)驗(yàn)證token判斷是否是合法的訪問(wèn)，注意，添加過(guò)濾器后需要在啟動(dòng)類上加上

@ServletComponentScan注解才能生效，具體實(shí)現(xiàn)如下：

import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.FilterConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;

/**
 * 解決swagger-ui 未授權(quán)訪問(wèn)漏洞，需要在啟動(dòng)類加@ServletComponentScan注解
 * 
 * @author ldy
 * @since V1.0.0
 */
@Slf4j
@WebFilter(urlPatterns = {"/v3/api-docs",
        "/swagger-ui/index.html"}, filterName = "springDocFilter")
public class SpringDocFilter implements Filter {

    /**
     * 訪問(wèn)swagger的token
     */
    @Value("${swagger.token:123@abc}")
    private String swaggerToken;

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        Filter.super.init(filterConfig);
    }

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;
        log.info("do springDocFilter,url:{}", request.getRequestURL());
        // 請(qǐng)求來(lái)源地址
        String referer = request.getHeader("referer");
        log.info("referer is {}", referer);

        /**
         * 1、請(qǐng)求來(lái)源地址為空,判斷token是否匹配 2、請(qǐng)求來(lái)源地址不為空，判斷來(lái)源地址是否包含正確的token
         */
        if (StringUtils.isBlank(referer)) {
            // 獲取token
            String token = request.getParameter("token");
            log.info("token is {}", token);
            // 來(lái)源地址為空，判斷token是否匹配
            if (!StringUtils.equals(swaggerToken, token)) {
                log.error("禁止未授權(quán)訪問(wèn),url:{}", request.getRequestURL());
                response.setStatus(403);
                servletResponse.setContentType("application/json");
                servletResponse.setCharacterEncoding("UTF-8");
                servletResponse.getWriter().write(JsonUtil.toJsonString(DJResult.error(-1, "禁止未授權(quán)訪問(wèn)", "")));
                return;
            }
        } else if (!referer.contains(swaggerToken)) {
            log.warn("禁止未授權(quán)訪問(wèn),url:{}", request.getRequestURL());
            response.setStatus(403);
            servletResponse.setContentType("application/json");
            servletResponse.setCharacterEncoding("UTF-8");
            servletResponse.getWriter().write(JsonUtil.toJsonString(DJResult.error(-1, "禁止未授權(quán)訪問(wèn)", "")));
            return;
        }


        filterChain.doFilter(servletRequest, servletResponse);
    }

    @Override
    public void destroy() {
        Filter.super.destroy();
    }
}

通過(guò)添加如上所示的過(guò)濾器后，我們就可以通過(guò)在路徑后面加上token參數(shù)進(jìn)行訪問(wèn)文檔地址了，如：127.0.0.1:8080/swagger-ui/index.html?token=123@abc。

沒(méi)有加token參數(shù)或者token參數(shù)匹配不上的請(qǐng)求會(huì)直接返回“禁止未授權(quán)訪問(wèn)”。

這里的token盡量設(shè)置復(fù)雜一點(diǎn)。