SpringBoot3.x整合Swagger的過(guò)程及注意事項(xiàng)

更新時(shí)間：2025年11月19日 09:13:52 作者：u***4207

Swagger是一個(gè)用于生成、描述、調(diào)用和可視化Restful風(fēng)格的web服務(wù)的規(guī)范和完整框架,接下來(lái)通過(guò)本文給大家介紹

產(chǎn)生背景

隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來(lái)的后端渲染，變成了前后端分離的形態(tài)，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠(yuǎn)。前端和后端的唯一聯(lián)系，變成了 API 接口，所以 API 文檔變成了前后端開(kāi)發(fā)人員聯(lián)系的紐帶，變得越來(lái)越重要。
那么問(wèn)題來(lái)了，隨著代碼的不斷更新，開(kāi)發(fā)人員在開(kāi)發(fā)新的接口或者更新舊的接口后，由于開(kāi)發(fā)任務(wù)的繁重，往往文檔很難持續(xù)跟著更新，Swagger 就是用來(lái)解決該問(wèn)題的一款重要的工具，對(duì)使用接口的人來(lái)說(shuō)，開(kāi)發(fā)人員不需要給他們提供文檔，只要告訴他們一個(gè) Swagger 地址，即可展示在線的 API 接口文檔，除此之外，調(diào)用接口的人員還可以在線測(cè)試接口數(shù)據(jù)，同樣地，開(kāi)發(fā)人員在開(kāi)發(fā)接口時(shí)，同樣也可以利用 Swagger 在線接口文檔測(cè)試接口數(shù)據(jù)，這給開(kāi)發(fā)人員提供了便利。

官方解釋：

Swagger是全球最大的OpenAPI規(guī)范（OAS）API開(kāi)發(fā)工具框架，支持從設(shè)計(jì)和文檔到測(cè)試和部署的整個(gè)API生命周期的開(kāi)發(fā)。Swagger是個(gè)于成服務(wù)器接的規(guī)范性檔、并且能夠?qū)舆M(jìn)測(cè)試的具。

簡(jiǎn)單來(lái)說(shuō)：Swagger是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化Restful風(fēng)格的web服務(wù)。

作用

接口的文檔在線自動(dòng)生成
功能測(cè)試

SpringBoot3整合Swagger注意事項(xiàng)

SpringBoot3+jdk17的情況下，swagger的V2和V3都是不行的。這里使用spring官方出品的springdoc-openapi。在使用springdoc-openapi的時(shí)候也有很多坑，首先springdoc-openapi的v1.x.x版本也是不行的，springdoc-openapi的版本必須是v2.x.x以上。

swagger3 常用注解

注解SpringBoot3 版本

替換舊注解 SpringBoot2 版本

描述

@Tag

@Api

用于標(biāo)注一個(gè)Controller（Class）。在默認(rèn)情況下，Swagger-Core只會(huì)掃描解析具有@Api注解的類，而會(huì)自動(dòng)忽略其他類別資源（JAX-RS endpoints，Servlets等等）的注解。

@Operation

@ApiOperation

用于對(duì)一個(gè)操作或HTTP方法進(jìn)行描述。具有相同路徑的不同操作會(huì)被歸組為同一個(gè)操作對(duì)象。不同的HTTP請(qǐng)求方法及路徑組合構(gòu)成一個(gè)唯一操作。

@Parameter

@ApiParam

@Parameter作用于請(qǐng)求方法上，定義api參數(shù)的注解。

@Parameters、@Parameter

@ApiImplicitParams、@ApiImplicitParam

都可以定義參數(shù)
（1）@Parameters：用在請(qǐng)求的方法上，包含一組參數(shù)說(shuō)明
（2）@Parameter：對(duì)單個(gè)參數(shù)的說(shuō)明

io.swagger.v3.oas.annotations新包中的@ApiResponses、@ApiResponse

舊包io.swagger.annotations中的@ApiResponses、@ApiResponse

進(jìn)行方法返回對(duì)象的說(shuō)明。

@Schema

@ApiModel、@ApiModelProperty

@Schema用于描述一個(gè)Model的信息（這種一般用在post創(chuàng)建的時(shí)候，使用@RequestBody這樣的場(chǎng)景）。

SpringBoot3.x整合Swagger

1.創(chuàng)建工程(jdk:17,boot:3.2.4)

項(xiàng)目結(jié)構(gòu)：

2.引入pom依賴

       <!-- openAPI包，替換 Swagger 的 SpringFox -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>
			  <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

3.application.yml添加配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4.添加swagger3.0配置

package com.example.config;
import io.swagger.v3.oas.models.ExternalDocumentation;
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;
/**
 * @author: Susheng
 * @datetime: 2024/3/26
 * @desc:
 */
@Configuration
public class OpenAPIConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("接口文檔標(biāo)題")
                        .description("SpringBoot3 集成 Swagger3接口文檔")
                        .version("v1"))
                .externalDocs(new ExternalDocumentation()
                        .description("項(xiàng)目API文檔")
                        .url("/"));
    }
}

5.控制器層(Controller)

package com.example.controller;
import com.example.model.SwaggerApiModel;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
/**
 * @author: zjl
 * @datetime: 2024/3/26
 * @desc:
 */
@Tag(name = "控制器：測(cè)試Swagger3", description = "描述：測(cè)試Swagger3")
@RestController
public class SwaggerController {
    @Operation(summary = "測(cè)試Swagger3注解方法Get")
    @Parameters({@Parameter(name = "id",description = "編碼"),
            @Parameter(name = "headerValue",description = "header傳送內(nèi)容")})
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "請(qǐng)求成功"),
            @ApiResponse(responseCode = "400", description = "請(qǐng)求參數(shù)沒(méi)填好"),
            @ApiResponse(responseCode = "401", description = "沒(méi)有權(quán)限"),
            @ApiResponse(responseCode = "403", description = "禁止訪問(wèn)"),
            @ApiResponse(responseCode = "404", description = "請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
    @GetMapping(value = "/swagger/student")
    public Object getStudent(@RequestParam @Parameter(example = "2")  String id,
                             @RequestHeader @Parameter(example = "2") String headerValue){
        return id;
    }
    @Operation(summary = "測(cè)試Swagger3注解方法Post")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "請(qǐng)求成功"),
            @ApiResponse(responseCode = "400", description = "請(qǐng)求參數(shù)沒(méi)填好"),
            @ApiResponse(responseCode = "401", description = "沒(méi)有權(quán)限"),
            @ApiResponse(responseCode = "403", description = "禁止訪問(wèn)"),
            @ApiResponse(responseCode = "404", description = "請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
    @PostMapping(value = "/swagger/student", produces = "application/json")
    public SwaggerApiModel updateStudent(@RequestBody SwaggerApiModel model){
        return model;
    }
    /**
     * swagger 不暴漏該 api，通過(guò)@Hidden隱藏
     * 但是仍然可以訪問(wèn)
     * @return
     */
    @Hidden
    @GetMapping(value = "/swagger/hiddenApi")
    public String hiddenApi(){
        return "hiddenApi";
    }
    /**
     * swagger 暴漏該 api，沒(méi)有配置@Hidden會(huì)展示
     * @return
     */
    @GetMapping(value = "/swagger/noHiddenApi")
    public String noHiddenApi(){
        return "noHiddenApi";
    }
}

6.模型層(Model)

package com.example.model;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;
/**
 * @author: zjl
 * @datetime: 2024/3/26
 * @desc:
 */
@Data
@Schema(description= "學(xué)生信息")
public class SwaggerApiModel implements Serializable {
    @Schema(description = "主鍵ID", required = true, example = "1")
    private Long id;
    @Schema(description = "手機(jī)號(hào)", required = true)
    private String phonenum;
    @Schema(description = "密碼", required = true)
    private String password;
    @Schema(description = "年齡", required = true)
    private Integer age;
}