快捷導(dǎo)航

SpringBoot3.x整合Swagger的過程及注意事項

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

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

產(chǎn)生背景

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

官方解釋：

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

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

作用

接口的文檔在線自動生成
功能測試

SpringBoot3整合Swagger注意事項

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

swagger3 常用注解

注解SpringBoot3 版本

替換舊注解 SpringBoot2 版本

描述

@Tag

@Api

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

@Operation

@ApiOperation

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

@Parameter

@ApiParam

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

@Parameters、@Parameter

@ApiImplicitParams、@ApiImplicitParam

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

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

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

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

@Schema

@ApiModel、@ApiModelProperty

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

SpringBoot3.x整合Swagger

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

項目結(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("項目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 = "控制器：測試Swagger3", description = "描述：測試Swagger3")
@RestController
public class SwaggerController {
    @Operation(summary = "測試Swagger3注解方法Get")
    @Parameters({@Parameter(name = "id",description = "編碼"),
            @Parameter(name = "headerValue",description = "header傳送內(nèi)容")})
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "請求成功"),
            @ApiResponse(responseCode = "400", description = "請求參數(shù)沒填好"),
            @ApiResponse(responseCode = "401", description = "沒有權(quán)限"),
            @ApiResponse(responseCode = "403", description = "禁止訪問"),
            @ApiResponse(responseCode = "404", description = "請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
    })
    @GetMapping(value = "/swagger/student")
    public Object getStudent(@RequestParam @Parameter(example = "2")  String id,
                             @RequestHeader @Parameter(example = "2") String headerValue){
        return id;
    }
    @Operation(summary = "測試Swagger3注解方法Post")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "請求成功"),
            @ApiResponse(responseCode = "400", description = "請求參數(shù)沒填好"),
            @ApiResponse(responseCode = "401", description = "沒有權(quán)限"),
            @ApiResponse(responseCode = "403", description = "禁止訪問"),
            @ApiResponse(responseCode = "404", description = "請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
    })
    @PostMapping(value = "/swagger/student", produces = "application/json")
    public SwaggerApiModel updateStudent(@RequestBody SwaggerApiModel model){
        return model;
    }
    /**
     * swagger 不暴漏該 api，通過@Hidden隱藏
     * 但是仍然可以訪問
     * @return
     */
    @Hidden
    @GetMapping(value = "/swagger/hiddenApi")
    public String hiddenApi(){
        return "hiddenApi";
    }
    /**
     * swagger 暴漏該 api，沒有配置@Hidden會展示
     * @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ī)號", required = true)
    private String phonenum;
    @Schema(description = "密碼", required = true)
    private String password;
    @Schema(description = "年齡", required = true)
    private Integer age;
}