swagger简单使用学习

注意

一下基于spring-boot 3.0.2版本，该版本不支持springfox-swagger2 2.9.2会报错，无法访问swagger

安装

在pomx文件中添加对应的依赖

 <!-- swagger -->
 <dependency>
     <groupId>org.springdoc</groupId>
     <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
     <version>2.1.0</version> <!-- 确保使用与 Spring Boot 兼容的最新版本 -->
 </dependency>

新版本不需要配置类，安装好依赖后，启动项目，可以直接访问http://localhost:8080/swagger-ui/index.html

效果图：

常用语法

修改文档信息

如果需要修改文档信息，则需要使用配置类

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档标题") // 设置 API 文档标题
                        .description("这是 API 文档的描述") // 设置 API 文档描述
                        .version("1.0.0") // API 文档版本
                        .contact(new Contact()
                                .name("开发者姓名")
                                .email("开发者邮箱")
                                .url("开发者个人网站或公司网站"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://springdoc.org"))); // 设置开源协议信息
    }
}

目录结构

效果

controller信息配置

controller添加描述信息

修改前

修改后

@Controller
@RequestMapping("/user")
@Tag(name="用户控制器",description = "处理用户相关操作")
public class UserController {

    @Autowired
    private UserService userService;
    
    
    // 根据用户id查询用户信息
    @Operation(summary = "根据id获取用户",description = "返回用户信息")
    @GetMapping("/findById")
    @ResponseBody
    public Result findById(Integer id) {
        User user = userService.findById(id);
        return new Result(0, "查询成功", user);
    }
}

• @Tag：用于为整个控制器添加描述信息，可以指定控制器的名称 (name) 和描述 (description)。
• @Operation：用于为具体的 API 操作（方法）添加摘要 (summary) 和详细描述 (description)。
  

入参描述

简单参数

 @Operation(summary = "根据id获取用户",description = "返回用户信息")
  @GetMapping("/findById")
  @ResponseBody
  public Result findById(@Parameter(description = "用户id") Integer id) {
      User user = userService.findById(id);
      return new Result(0, "查询成功", user);
  }

复杂对象入参

需要在参数实体类中添加

class UserParam {
    @Schema(description = "用户的唯一标识符，list集合", example = "[12345]")
    private List<Integer> idList;
}

返回值描述

在返回值的实体类中使用@Schema注解

public class Result<T> {
    @Schema(description = "业务状态码  0-成功  1-失败")
    private Integer code;//业务状态码  0-成功  1-失败
    @Schema(description = "提示信息")
    private String message;//提示信息
    
    ...
}

需要注意的是controller接口的返回值要指定具体的实体类，否则swagger里无法显示

正确

 @Operation(summary = "根据id获取用户", description = "返回用户信息")
 @GetMapping("/findById")
 @ResponseBody
 public Result<User> findById(@Parameter(description = "用户id") Integer id) {
     User user = userService.findById(id);
     return Result.success(user);
 }

错误（不影响代码运行，但是没有具体的返回值）

 @Operation(summary = "根据id获取用户", description = "返回用户信息")
 @GetMapping("/findById")
 @ResponseBody
 public Result findById(@Parameter(description = "用户id") Integer id) {
     User user = userService.findById(id);
     return Result.success(user);
 }