SpingBoot中使用Swagger快速生成接口文档

news2024/12/25 10:21:48

一.Swagger快速上手

二.Swagger中的基本注解

三.使用Swagger进行测试

一.Swagger快速上手

Swagger是⼀个接⼝⽂档⽣成⼯具，它可以帮助开发者⾃动⽣成接⼝⽂档。当项⽬的接⼝发⽣变更时，Swagger可以实时更新⽂档，确保⽂档的准确性和时效性。Swagger还内置了测试功能，开发者可以直接在⽂档中测试接⼝，⽆需编写额外的测试代码。

使用起来也很简单，直接引入其依赖即可

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>

依赖引入后即可进行相应的配置，如下就是一个简单的配置示例，你可以在这个配置项中声明接口文档的名称以及相关的描述，这些描述并不是必须的，可以省略。

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("在线oj系统")
                        .description("在线oj系统接⼝⽂档")
                        .version("v1"));
    }
}

如果你使用的是微服务的架构，为了使该配置项在其他服务中也生效，则需要声明该配置项的位置。即如下图所示在 resource包下声明该配置类的路径。

然后启动项目，访问swagger-ui即可看见当前项目中接口的信息了

同时这些接口中也包含了自动测试的方法，我们点击即可一键进行测试

二.Swagger中的基本注解

为了使该接口文档更丰富，我们可以使用swagger为我们提供的一些基本注解来进行一些自定义的申明，以下是一些常用的注解

@Tag

介绍：⽤于给接⼝分组，⽤途类似于为接⼝⽂档添加标签。

⽤于：⽅法、类、接⼝。

常⽤属性：

name：分组的名称

如下代码，就是使用了@Tag为整个Controller进行了统一的命名分组。

@RestController
@RequestMapping("/sysUser")
@Tag(name = "管理员用户API")
public class SysUserController {
    //... ...
}

@Operation

介绍：⽤于描述接⼝的操作。

⽤于：⽅法。

常⽤属性：

summary：操作的摘要信息。

description：操作的详细描述。

@Parameters

介绍：⽤于指定@Parameter注解对象数组，描述操作的输⼊参数。

⽤于：⽅法。

@Parameter

介绍：⽤于描述输⼊参数。

⽤于：⽅法。

常⽤属性：

name：参数的名称。

in：参数的位置，可以是 path、query、header、cookie 中的⼀种。

description：参数的描述。

@ApiResponse

介绍：⽤于描述操作的响应结果.

⽤于：⽅法。

常⽤属性：

responseCode：响应的状态码。

description：响应的描述。

就拿下面这个示例来说

@Operation注解就申明了这个接口是用来查询用户详情的
@Parameters注解表明了这个接口需要传入的参数，其中@parameter用于修饰每一个参数
@ApiResponse注解则申明了需要给前端返回怎么样的数据，状态码以及对应的信息

/**
 * 根据条件查询管理员用户
 *
 * @param userId
 * @param sex
 * @return
 */
@GetMapping("/detail")
@Operation(summary = "⽤⼾详情", description = "根据查询条件查询⽤⼾详情")
@Parameters(value = {
        @Parameter(name = "userId", in = ParameterIn.QUERY, description = "⽤⼾ID"),
        @Parameter(name = "sex", in = ParameterIn.QUERY, description = "⽤⼾性别")
})
@ApiResponse(responseCode = "1000", description = "成功获取⽤⼾信息")
@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")
@ApiResponse(responseCode = "3101", description = "⽤⼾不存在")
public R<SysUserVO> detail(@RequestParam(required = true) Long userId, @RequestParam(required = false) String sex) {
    return null;
}

@Schema

介绍：⽤于描述数据模型的属性。

⽤于：⽅法、类、接⼝。

常⽤属性：

description：响应的描述。

如下是个实体类用来封装数据，使用了@Schema注解对字段进行了描述

@Getter
@Setter
public class SysUserVO {
    
    @Schema(description = "用户账号")
    private String userAccount;
    
    @Schema(description = "用户昵称")
    private String nickName;
}