Swagger的使用教程

前言

什么是Swagger？

        官网：https://swagger.io/

        Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要是生成规范的后端接口文档，并兼顾后端接口测试功能。

为什么使用Swagger？

        起初，后端开发过程中，程序员需要创建一份API文档来记录所有的接口细节，供其他开发人员使用提供的接口服务，但会存在以下的问题：

• 接口众多，并且细节复杂

• 需要根据接口的变化，不断修改API文档，非常麻烦，费时费力

Swagger的出现就是为了解决上述的这些问题，减少创建API文档的工作量。

• 后端人员在代码里添加接口的说明内容，就能够生成可预览的API文档，无须再维护Word文档

• 让维护文档和修改代码整合为一体，在修改代码逻辑的同时方便的修改文档说明

• 提供了页面测试功能，便于对接口进行测试

使用

环境准备

        Swagger一般都是配合SpringBoot项目使用的，所以在使用时要创建SpringBoot项目，并通过MybatisPlus的代码生成器快捷生成三层结构代码。可以参考以下文章

ieda2019-创建SpringBoot项目-CSDN博客

Mybatis-Plus框架——1.代码生成器的使用_baomidou代码生成器-CSDN博客

1.配置Swagger

1.添加依赖。在pom.xml文件中添加相关的依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2.创建配置类。创建一个config目录，并在该目录下创建配置类

• @Configuration：表示这是一个 Spring 的配置类，Spring 容器会在启动时加载这个类中的 Bean。
• @EnableKnife4j：启用 Knife4j，这是对 Swagger 的增强 UI 实现，提供了更美观、功能更强的接口文档展示界面。

@Configuration
@EnableKnife4j // 启用Knife4j
public class SwaggerConfig {

    /**
     * 创建Restful API文档内容
     */
    @Bean
    public Docket Api() {
        return new Docket(DocumentationType.SWAGGER_2)      //指定使用 Swagger 2 规范生成文档
                .apiInfo(apiInfo())                        //设置 API 文档的基本信息（标题、描述等）
                .groupName("Swagger测试项目模块")           //分组名称，多个 Docket 可以分组展示不同模块的接口
                .select()
                // 指定要暴露的接口所在包
                .apis(RequestHandlerSelectors.basePackage("com.cdy.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API的基本信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger项目后端API接口文档")
                .description("欢迎访问后端API接口文档")
                .contact(new Contact("chendy","","cdy@qq.com"))
                .version("1.0")
                .build();
    }
}

3.配置application.yml文件。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 用于解决SpringBoot2.6+版本与Swagger的兼容性问题

4.在主程序中配置注解@ComponentScan，需要扫描到swagger的配置类，否则不显示Swagger文档信息。

@SpringBootApplication
@MapperScan("com.cdy.mapper") // 替换为你实际的 mapper 包路径
@ComponentScan(basePackages = {"com.cdy.**.**"}) //使用通配符表示 Spring Boot 将扫描 com.cdy 包下所有的子包中的组件
public class SpringBootMpApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootMpApplication.class, args);
    }

}

• @SpringBootApplication ：是一个复合注解，包含以下三个核心注解
•         @Configuration：表示该类为配置类，相当于 XML 配置文件的作用
•         @EnableAutoConfiguration：启用 Spring Boot 自动配置机制
•         @ComponentScan：默认扫描当前类所在包及其子包下的所有组件。
• @MapperScan ：  Spring Boot 在启动时会自动扫描该包下的接口，并将它们注册为 MyBatis 的 Mapper。这样不需要再每个接口上都添加@Mapper。
• @ComponentScan ： 扫描basePackages路径下的所有组件类。

@ComponentScan(basePackages = {"com.cdy.**.**"}) 和@SpringBootApplication的作用是否冲突？

        不冲突，@SpringBootApplication默认已经扫描了当前类所在包及其子包，但有时实际项目中，许多模块时不在主程序类所在包中的，为了更灵活控制或确保某些模块不被遗漏，可以显式加上@ComponentScan

5.查看接口文档

访问http://localhost:端口/doc.html，查看接口文档。以下的一些参数信息便是配置类中配置读取的。

2.文档生成设置

使用Swagger提供的注解对接口进行说明，常用注解：

• @Api 标注在类上，对类进行说明

• @ApiOperation 标注在方法上，对方法进行说明

• @ApiParam 标注在参数上，对方法的参数进行说明

• @ApiModel 标注在模型Model上，对模型进行说明

• @ApiModelProperty 标注在属性上，对模型的属性进行说明

• @ApiIgnore 标注在类或方法上，表示忽略这个类或方法

这里说的Model指的是实体类如Dept类。

1. 在模型类中使用的注解。

这里以Dept类为例，该注解是使用代码生成器时【gc.setSwagger2(true); //启用Swagger注解】，这样会自动为实体类配置生成@ApiModel和@ApiModelProperty。

package com.cdy.po;
import com.baomidou.mybatisplus.annotation.TableName;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
/**
 * <p>
 * 部门表
 * </p>
 *
 * @author 作者名
 * @since 2025-06-13
 */
@Data
@EqualsAndHashCode(callSuper = false)
@TableName("t_dept")
@ApiModel(value="Dept对象", description="部门表")
public class Dept implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "编号")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;

    @ApiModelProperty(value = "部门名称")
    private String name;

}

2. 在controller类中使用注解和方法。

package com.cdy.controller;


import com.cdy.po.Dept;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * <p>
 * 部门表 前端控制器
 * </p>
 *
 * @author 作者名
 * @since 2025-06-13
 */
@Api(tags = "部门表")
@RestController
@RequestMapping("/dept")
public class DeptController {
    @PostMapping("/addDept")
    @ResponseBody
    @ApiOperation("添加部门")
    public void addDept(@RequestBody Dept dept){
        System.out.println(dept);
    }

    @GetMapping("/getdevcieInfo")
    @ResponseBody
    public void getdevcieInfo(@ApiParam(value = "部门ID", required = true, example = "123") int id) {
        System.out.println(id);
    }

}

@RequestBody是配合@ApiModel和@ApiModelProperty使用的

        当前端传参为请求体接收时，即使用@RequestBody时，应该在请求体对象中（如Dept）使用 @ApiModel和 @ApiModelProperty 来描述整个请求体对象。

@RequestParam是配合@ApiParam使用的

        当前端传参为单个参数时，可以使用@ApiParam对该参数进行基本的信息描述。

这里要做好区分。

3.结果

当Controller类中写好@PostMapping和@GetMapping等方法时，如果不使用Swagger的注解话，会使用默认写法。而使用对应的注解可以对该接口进行说明，更容易理解。如果没写@PostMapping和@GetMapping等方法，则不会显示该接口的文档。例如UserController类。

3.文档测试说明和使用

3.1 文档说明

1.主页模块

主页模块主要是配置类中配置的一些基本参数信息。其中接口统计信息会对请求类型的对应方法数量进行统计。

2. Swagger Models模块

该模块主要包含对实体类的介绍说明，对应@ApiModel和@ApiModelProperty。同时只有模块被使用才会出现在这里，如DeptController类中接收消息体【(@RequestBody Dept dept】，若未使用实体类，即使在实体类中标明注解也不显示。

3.文档管理模块

该模块的核心是全局参数的设置，对于实际项目的用户登录后会携带token访问页面，所以这里添加全局的token后（参数类型选header），会在每个测试接口的请求头部编辑该token参数。同时如果参数类型改为query，则该token会在测试接口的请求参数中。这里主要是将token用作请求头参数。

4.接口测试模块

该模块的核心在于调试页面。左侧是调试接口的分类，文档页面中是调试接口的说明。调试页面的核心是请求参数的三个类别的说明，以下会具体说明。对于请求参数一般都是根据后端程序接收参数的类型来定义的。

4.1 x-www-form-urlencoded参数。

        当选择 x-www-form-urlencoded 作为请求体类型时，发送的数据会被编码成 URL 编码格式（类似于查询字符串的格式）。键值对被编码为键=值的形式，并且使用&符号连接。

        图片中，方式二的参数会被编码为方式一的形式发送到后端。方式二的作用是方便书写（直接以方式一发送请求也可以）。

        程序中接收的参数格式为单个参数格式。

4.2 raw 参数

        raw: 允许你手动输入原始的请求体内容，支持多种格式如 JSON、XML、Text等，适用于更复杂的数据结构。这一般是前端的表单形式配合后端的接收类结合使用。

        程序中接收参数的格式为实体类格式。

4.3 form-data参数

        form-data: 主要用于支持文件上传的表单提交，可以包含文本数据和文件数据。

        程序中接收的参数类型为文件类型。

 

3.2测试案例测试

案例代码

@RestController
@Api(tags = "测试案例")
@RequestMapping("/test")
public class TestController {

    @ApiOperation("上传文件测试接口")
    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public Map<String, String> uploadFile(@RequestPart("file") MultipartFile file) {
        Map<String, String> result = new HashMap<>();
        if (!file.isEmpty()) {
            result.put("fileName", file.getOriginalFilename());
            result.put("contentType", file.getContentType());
            result.put("status", "success");
        } else {
            result.put("status", "fail");
            result.put("message", "文件为空");
        }
        return result;
    }
    @ApiOperation(value = "单参数测试接口")
    @GetMapping("/ParamTest")
    public String ParamTest(int id,String name) {
        return "输入的id和name："+id+","+name;
    }

    @ApiOperation(value = "数组测试接口")
    @GetMapping("/IntegerArrTest")
    public String IntegerArrTest(Integer[] integers) {
        return "receive: " + Arrays.toString(integers);
    }

    @ApiOperation(value = "列表测试接口")
    @GetMapping("/ListTest")
    public String ListTest(@RequestParam(value = "list") List<Integer> list) {
        return "receive: " + list.toString();
    }

    @ApiOperation(value = "实体类测试接口")
    @GetMapping("/addDept1")
    public String addDept1(Dept dept) {
        return "receive: " + dept.toString();
    }

    @ApiOperation(value = "实体类测试(以JSON格式传参)")
    @PostMapping("/addDept")
    public String addDept(@RequestBody Dept dept) {
        return "receive: " + dept.toString();
    }
}

测试结果

1.上传文件测试接口

2.单参数测试接口

3. 数组测试接口

4. 列表测试接口

5.实体类测试接口

6.实体类测试(以JSON格式传参)

总结

        以上便是Swagger的基础使用，核心还是理解测试页面参数的的含义，这样才可以更方便的使用理解。