# Springboot 集成 Swagger 入门

作者：刘小标

# 0 前言

前端：抱怨接口文档与实际不一致
后端：接口文档撰写、维护耗时费力
愿力：期望有一个好的接口文档

# 1 Swagger 简述

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。如何按照新的开发模式，在版本开发或者迭代版本的时候，只需要更新 Swagger 描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

即便如此，编写 yml 或 json 格式的描述文件，本身也是有一定负担的工作，特别是在持续迭代开发的时候，更容易忽略更新这个描述文件。久而久之，这个描述文件也和实际项目渐行渐远，基于改描述文件生成的文档也失去了参考意义。

所以， Spring 作为 Java 领域服务端的大佬，迅速讲 Swagger 规范纳入自身的标准，简历了 Spring-swagger 项目，后面改成了 Springfox。通过在项目种引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码

swagger官网

总结：swagger 就是一个用来定义接口标准，接口规范，根据代码自动生成接口文档的工具。

# 2 Swagger 工具

swagger工具

Swagger Codegen：通过 Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过 jar 包，docker，node 等方式在本地化执行生成。也可以在后面的 Swagger Editor 中在线生成。
Swagger Editor：编辑 Swagger 描述文件的编辑器（类似 Markdown 的编辑器），该编辑器支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger UI：提供了一个可视化的 UI 页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地化部署 UI 项目。
Swagger Inspector：是一个可以对接口进行测试的在线版的 postman。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 SwaggerHub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分为免费版和收费版。
Springfox Swagger：Spring 基于 swagger 规范，可以将基于 SpringMVC 和 Spring Boot 项目的代码，自动生成 JSON 格式的描述文件。不属于 Swagger 官网提供的。

# 3 构建 SpringBoot 和 Swagger 环境

# 3.1 引入依赖

springfox swagger2

<!--swagger2依赖-->
<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
11

# 3.2 配置 Swagger

/**
 * @author Lauxb
 * @version 1.0.0
 * @description
 * @date Created in 2020/7/17 14:57
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.dist.customer.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("标题：SpringBoot集成Swagger")
                //创建人
                .contact(new Contact("lauxb", "https://www.dist.com.cn", "liuxb@dist.com.cn"))
                //版本号
                .version("3.0")
                //描述
                .description("SpringBoot集成Swagger的详细描述信息。")
                .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
29
30
31
32
33
34

# 3.3 启动 SpringBoot

start springboot

# 3.4 访问 Swagger 页面

访问 swagger 的 ui 界面： http://localhost:8081/assets/img/swagger-ui.html

swaggerui

# 4 开发 Controller 接口

# 4.1 连接 Mysql

mysql

# 4.1 EasyCode 生成代码

Easycode

# 5 Swagger 注解

# 5.1 @Api

作用：用来指定接口的描述文字
修饰范围：用在类上

@RestController
@RequestMapping("userTable")
@Api(tags = "用户接口说明")
public class UserTableController extends ApiController {
	......
}

1
2
3
4
5
6

# 5.2 @ApiOperation

作用：用来对接口中具体方法作描述
修饰范围：用在方法上

@PostMapping
@ApiOperation(value = "新增一条用户信息",notes = "<font color='blue'>描述：</font> 新增一条用户信息")
public R insert(@RequestBody UserTable userTable) {
    return success(this.userTableService.save(userTable));
}

1
2
3
4
5

[x] value: 用来对接口的说明
[x] notes: 用来对接口的详细描述

# 5.3 @ApiModel

作用：用来对实体模型进行描述
修饰范围：用在实体模型上

@Data
@EqualsAndHashCode(callSuper = true)
@NoArgsConstructor
@ApiModel(description = "用户模型信息")
public class UserTable extends Model<UserTable> {
	...
}

1
2
3
4
5
6
7

# 5.4 @ApiModelProperty

作用：用来对实体模型属性作描述
修饰范围：用在模型属性上

@Data
@EqualsAndHashCode(callSuper = true)
@NoArgsConstructor
@ApiModel(description = "用户模型信息")
public class UserTable extends Model<UserTable> {

    @TableId(type = IdType.AUTO)
    @ApiModelProperty(name = "id", value = "用户id", hidden = true)
    private Long id;

    @ApiModelProperty(name = "name", value = "用户名称", dataType = "String", example = "java", position = 1)
    private String name;

    @ApiModelProperty(name = "sex", value = "用户性别", dataType = "String", example = "it", position = 2)
    private String sex;

    @ApiModelProperty(name = "tel", value = "用户电话", dataType = "String", example = "001 001", position = 3)
    private String tel;

    @ApiModelProperty(name = "addr", value = "用户地址", dataType = "String", example = "pc", position = 4)
    private String addr;
}

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

# 5.5 @ApiImplicitParam

作用：用来对接口方法参数作描述
修饰范围：用在方法上

@GetMapping("{id}")
@ApiOperation(value = "查询指定用户的信息",notes = "<font color='red'>描述：</font>用来查询指定用户信息的接口")
@ApiImplicitParam(name = "id",value = "用户id",dataType = "Serializable",defaultValue = "0")
public R selectOne(@PathVariable Serializable id) {
    return success(this.userTableService.getById(id));
}

1
2
3
4
5
6

# 5.6 @ApiResponses

作用：用于请求的方法上，表示一组响应
修饰范围：用在方法上

@DeleteMapping
@ApiResponses({
    @ApiResponse(code = 200,message = "请求成功。"),
    @ApiResponse(code = 401,message = "未授权！"),
    @ApiResponse(code = 403,message = "禁用！"),
    @ApiResponse(code = 404,message = "未找到！")
})
public R delete(@RequestParam("idList") List<Long> idList) {
    return success(this.userTableService.removeByIds(idList));
}

1
2
3
4
5
6
7
8
9
10