【SpringBoot整合系列】SpringBoot3.x整合Swagger

smxgn2026-03-17 8:17
目录

产生背景

  • 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前 端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了 API 接口，所以 API 文档 变成了前后端开发人员联系的纽带，变得越来越重要。

  • 那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的 繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人 来说，开发人员不需要给他们提供文档，只要告诉他们一个 Swagger 地址，即可展示在线的 API 接口 文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也 可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。

官方解释：

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。Swagger是个于成服务器接的规范性档、并且能够对接进测试的具。

简单来说：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务。

作用

  • 接口的文档在线自动生成
  • 功能测试

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

用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

@Operation

@ApiOperation

用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

@Parameter

@ApiParam

@Parameter作用于请求方法上，定义api参数的注解。

@Parameters、@Parameter

@ApiImplicitParams、@ApiImplicitParam

都可以定义参数

（1）@Parameters：用在请求的方法上，包含一组参数说明

（2）@Parameter：对单个参数的说明

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

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

进行方法返回对象的说明。

@Schema

@ApiModel、@ApiModelProperty

@Schema用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景）。

SpringBoot3.x整合Swagger

1.创建工程(jdk:17,boot:3.2.4)

项目结构：

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("接口文档标题")
                        .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传送内容")})
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "请求成功"),
            @ApiResponse(responseCode = "400", description = "请求参数没填好"),
            @ApiResponse(responseCode = "401", description = "没有权限"),
            @ApiResponse(responseCode = "403", description = "禁止访问"),
            @ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")
    })
    @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 = "请求参数没填好"),
            @ApiResponse(responseCode = "401", description = "没有权限"),
            @ApiResponse(responseCode = "403", description = "禁止访问"),
            @ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")
    })
    @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= "学生信息")
public class SwaggerApiModel implements Serializable {

    @Schema(description = "主键ID", required = true, example = "1")
    private Long id;

    @Schema(description = "手机号", required = true)
    private String phonenum;

    @Schema(description = "密码", required = true)
    private String password;

    @Schema(description = "年龄", required = true)
    private Integer age;

}

7.启动并测试

启动服务后，首先通过浏览器打开链接http://localhost:9090/swagger-ui/index.html

【Get请求接口】/swagger/student接口详情

  • 入参

  • 响应模板

  • 接口测试

  • 接口测试结果

Model详情
【POST请求接口】/swagger/student

相关推荐
devlei3 小时前
从源码泄露看AI Agent未来：深度对比Claude Code原生实现与OpenClaw开源方案
android·前端·后端
pshdhx_albert3 小时前
AI agent实现打字机效果
java·http·ai编程
沉鱼.444 小时前
第十二届题目
java·前端·算法
努力的小郑4 小时前
Canal 不难，难的是用好：从接入到治理
后端·mysql·性能优化
赫瑞5 小时前
数据结构中的排列组合 —— Java实现
java·开发语言·数据结构
Victor3565 小时前
MongoDB（87）如何使用GridFS？
后端
Victor3565 小时前
MongoDB（88）如何进行数据迁移？
后端
小红的布丁5 小时前
单线程 Redis 的高性能之道
redis·后端
GetcharZp5 小时前
Go 语言只能写后端？这款 2D 游戏引擎刷新你的认知！
后端
周末也要写八哥6 小时前
多进程和多线程的特点和区别
java·开发语言·jvm
热门推荐
01GitHub 镜像站点02OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程03AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南04Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）05VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）06【Vulhub】Fastjson 1.2.24_rce复现07Claude Code 未登录 使用第三方模型08UV安装并设置国内源09Oh My Codex 快速使用指南10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）