SpringBoot项目集成Swagger指南

一、引言：为什么需要Swagger？

根据我个人的一些经验，很多中小型软件公司目前依然在使用world在写内部接口文档，稍微好一点的还会使用到Apifox这种接口管理工具。很多时候前端找后端要接口，后端程序员都得找半天。而且这种手动编写的文档不仅费时费力难以维护，还容易出错，每次更新接口代码，都要修改，如果接口数量特别大，也没法保证文档风格统一，随之而来的弊端就是沟通成本非常高。

我觉得这种情况完全可以使用Swagger去避免。首先，Swagger的接口文档是自动生成的，修改代码并不用再调整文档内容；其次文档内容的风格统一，看着也舒服；最后一点，Swagger生成的接口文档是符合行业标准的。

二、环境准备

我使用的是SpringBootv3.5.5 + Java17

创建一个简单的SpringBoot Web项目
引入Swagger相关依赖springdoc-openapi-starter-webmvc-ui

注意事项： 由于Springfox Swagger2/3已停止更新，强烈推荐使用Springdoc-OpenAPI（它是Swagger UI的替代品，支持OpenAPI 3规范和新版Spring Boot）

然后无需配置，直接启动项目并访问：http://127.0.0.1:8080/swagger-ui/index.html

三、全局配置

关于Swagger首页的公共内容，一般要改成自己项目的内容，就需要用到全局配置，有两种静态资源配置的方式，只需要创建一个Swagger的配置类进行设置。

第一种方式，使用编程式配置：

java 复制代码

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("XX项目API文档")
                        .description("这是由Swagger3生成的API文档")
                        .version("版本：0.0.1"));
    }
}

title：文档标题
description：文档描述
version：文档版本

除了使用@Bean注入的方式，还可以使用注解的方式进行静态资源设置

第二种方式，使用`@OpenAPIDefinition`注解配置

java 复制代码

@Configuration
@OpenAPIDefinition(info = @Info(title ="XX项目API文档",description ="这是由Swagger3生成的API文档",version = "版本：0.0.1"))
public class SwaggerConfig {

}

两种配置方式的效果是一样的。

四、接口相关配置（重点）

在项目中，不可能所有的接口都要对外暴露文档，那么该如何指定如何指定哪些接口需要文档，哪些不需要呢？其次，项目中的接口是由不同的后端程序员开发，怎么知道Swagger文档中的接口是谁开发的？最后，接口文档中有各种请求和响应参数，如何对这些参数添加说明文字。

1. 配置需要创建文档的接口

如果想要让Swagger为我们生成接口文档，首先要告诉Swagger哪些接口需要生成文档。可以在SpringBoot的application.yml配置文件指定需要创建API文档的接口。

vbnet 复制代码

springdoc:
  group-configs[0].group: 测试
  group-configs[0].packages-to-scan: com.example.springswagger.controller
  group-configs[0].paths-to-match: /test/**

在上面的配置中group-configs表示分组配置，因为在实际的项目中我们往往需要针对某一个业务编写多个接口，对于这些同一业务组成的多个接口，我们可以将他们放在一个组中，避免混淆。其中group用来指定组名；packages-to-scan指定要扫描哪个包下的接口；paths-to-match则表示要匹配的接口路径。

在com.example.springswagger.controller包下，我编写了一个接口类：

java 复制代码

@RestController
public class SwaggerController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @GetMapping("/test")
    public String test(){
        return "test";
    }
}

由于Swagger的paths-to-match值为/test/**，所以在Swagger的API文档中，只能看到/test接口，看不到/hello接口。配置结果如下图所示：

packages-to-scan和paths-to-match可以配置多个匹配规则，需要用,隔开即可

javascript 复制代码

springdoc:
  ...
  group-configs[0].paths-to-match: /test/**,/hello/**

结果：

成功扫描多个配置。

2. 配置具体接口的解释说明

如果只是生成一个文档，没有任何说明文字，前端程序员很难理解API文档的内容，所以我们需要利用Swagger提供的一些注解让API文档更加完整。

首先，我们希望让Controller中的所有接口有一个统一的说明文字，只需要在接口类中加上@Tag注解并设置name和description属性的值：

java 复制代码

@Tag(name = "测试接口",description = "这是XX项目的一些测试接口，主要用来做测试")
@RestController
public class SwaggerController {
    //...
}

其次，还需要对具体的每个接口都设置说明信息，让前端知道接口的具体作用，这里需要利用@Operation注解实现：

java 复制代码

@Operation(summary = "测试打招呼接口")
@GetMapping("/hello")
public String hello(){
	return "hello";
}

效果：

现在文档的信息就比之前清晰多了，如果有需求的话，还可以在这些信息中加上开发者的姓名，方便对接时沟通。

3. 配置API请求及响应的报文说明

在日常开发过程中，请求和响应一般使用JSON格式的数据，这里先创建了两个实体类，分别是请求实体和响应实体，用来封装JSON数据。在实体类中，使用@Schema注解对实体和属性设置文档说明内容

请求实体测试类：

java 复制代码

@Data
@Schema(description = "测试实体类")
public class TestModel {
    @Schema(description = "名称",requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;
    @Schema(description = "描述")
    private String desc;
    @Schema(description = "测试数字",minimum = "1",maximum = "10")
    private Integer testNum;
}

响应实体测试类

java 复制代码

@Data
@Schema(description = "返回报文实体类")
public class ResultModel {

    public ResultModel(Integer code,String msg){
        this.msg = msg;
        this.code = code;
    }
    public static ResultModel ok(){
        return new ResultModel(200, "测试成功");
    }

    @Schema(description = "响应码",requiredMode = Schema.RequiredMode.REQUIRED)
    private Integer code;
    @Schema(description = "响应描述",requiredMode = Schema.RequiredMode.REQUIRED)
    private String msg;
}

其中@Schema中的description用来指定报文的描述和属性的描述，requiredMode设置具体的参数是否为必填项，对于数字类型的参数，可以使用minimum、maximum设置数值的范围。这些信息都是为了告诉接口调用者们，请求参数的规则。

创建完数据模型，还需要修改一下/test接口的代码：

java 复制代码

@Operation(summary = "测试接口")
@PostMapping("/test")
public ResultModel test(@RequestBody TestModel model){
	return ResultModel.ok();
}

将接收和返回的数据修改为上面创建的两个实体类的对象。然后重新启动项目，打开/testAPI文档：

可以看到，请求的数据和请求参数的描述都被成功创建了，再看下文档中的返回报文部分：

这些都是SpringBoot和Swagger基于代码中的约定设置自动帮我们创建完成的。

需要注意的是，在设置完接口的请求和响应实体类后，Swagger会在页面上帮我们生成实体类的说明文档，单独显示在Schemas模块下：

如果希望将其隐藏，只需要在application.yml中设置springdoc.swagger-ui.defaultModelsExpandDepth: -1即可。

五、总结

总而言之，集成Swagger绝非仅仅是引入一个依赖库，它更代表着一种开发理念的升级。通过本文的实践，我们成功地将API文档从静态、孤立的文本文件，转变为动态、可交互的开发工具。它使得文档始终与代码同步，让后端开发、前端对接和测试验证工作形成了无缝闭环。拥抱Swagger，就是拥抱高效、规范与协作，是迈向专业化协作开发的重要一步。

SpringBoot项目集成Swagger指南

一、引言：为什么需要Swagger？

二、环境准备

三、全局配置

第一种方式，使用编程式配置：

第二种方式，使用@OpenAPIDefinition注解配置

四、接口相关配置（重点）

1. 配置需要创建文档的接口

2. 配置具体接口的解释说明

3. 配置API请求及响应的报文说明

五、总结

第二种方式，使用`@OpenAPIDefinition`注解配置