SpringBoot+Swagger,快速构建REST API文档

上一篇使用Hibernate-validator的Notnull等注解校验参数并使用全局异常处理提到项目文档丢失，这一片讲一下用Swagger生成文档，让文档再也不丢失吧...

# 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

# 使用

Pom：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

1
2
3
4
5
6
7
8
9
10

配置类：

@EnableSwagger2
@Configuration
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("组名")
        .apiInfo(apiInfo())
        .select()
        // 为当前包下controller生成API文档
        .apis(RequestHandlerSelectors.basePackage("com.dram.swaggerdemo.controller"))
        // 为有@Api注解的Controller生成API文档
        //                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
        // 为有@ApiOperation注解的方法生成API文档
        //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("SwaggerUI演示")
        .description("用于演示SwaggerUI")
        .version("1.0")
        .build();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

实体类：

@Data
@Builder
@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户ID")
    private Long id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("用户密码")
    private String password;
}

@Data
@AllArgsConstructor
public class Result<T> {
    @ApiModelProperty(value = "状态码")
    private Integer code;
    @ApiModelProperty(value = "数据")
    private T data;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

控制器：

@RestController
@RequestMapping("user")
@Api(value = "用户相关控制",tags = "用户控制器")
public class UserController {

  @ApiOperation(value = "获取用户",notes = "获取一个用户")
  @GetMapping("get/{id}")
  public Result<User> get(@ApiParam(value = "用户ID",example = "100")    @PathVariable Long id) {
    return new Result<>(200, User.builder().id(id).name("张三").password("1234").build());
  }

  @PostMapping("add")
  public Result<Boolean> add(@RequestBody User user){
    return new Result<>(200,true) ;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

运行项目，打开 http://localhost:8088/swagger-ui.html 就可以看到文档啦。

# 常用注解详解

@Api(tag = "接口名",description = "接口描述",hidden = true时隐藏)：修饰整个类，描述Controller的作用
@ApiOperation(value = "接口说明",notes = "接口发布说明")：用在请求的方法上，说明方法的作用
@ApiParam(value = "参数简单描述",defaultValue = "描述默认值",required = 是否必传,allowableValues = "可接受的值")：单个参数描述
@ApiModel：用在JavaBean类上，说明JavaBean的用途
@ApiProperty(value = "字段说明",required = 是否必传,example = 举例说明，allowableValues = "可接受的值")：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API

#SpringBoot #Swagger

上次更新: 10/23/2024

← 简陋的注解扫描实现 Spring&kotlin 异常 NoClassDefFoundError→