SpringBoot2 | 第十七篇:集成Swagger2在线调试(官方版)

Swagger

​ 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

​ 前端和后端 唯一联系,变成了 API 接口;API文档 自然就成了前后端开发人员联系的纽带,变得尤为的重要,swagger就是一款让你更好的书写API文档的框架。

Swagger 是一款自动生成 在线文档 + 接口调试 的工具。在 WEB 开发中不可否认的是我们需要给客户端提供 API 接口,这个时候需要借助 postman、rap 等工具 进行调试,以便于接口能正常交付给客户端人员,用过其它工具的应该知道一个 POST 请求一堆参数是非常枯燥且烦人的事情,而 Swagger 就是让你摆脱这种束缚感….

swagger 优缺点

  • 集成方便,功能强大
  • 在线调试与文档生成
  • 代码耦合,需要注解支持,但不影响程序性能

环境/版本一览:

  • 开发工具:Intellij IDEA 2018.2.2
  • springboot: 2.0.5.RELEASE
  • jdk:1.8.0_171
  • maven:3.3.9
  • springfox-swagger2:2.8.0
  • springfox-swagger-ui:2.8.0

1、pom.xml

swagger 需要的依赖有两个:springfox-swagger2springfox-swagger-ui,版本要求一致

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
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
<!-- swagger2 begin -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<!-- swagger2 end -->
</dependencies>

2、config

@EnableSwagger2 开启 swagger2

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
35
36
37
38
39
40
41
package com.fatal.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* Swagger2 配置类
* @author: Fatal
* @date: 2018/10/17 0017 14:54
*/
@Configuration
@EnableSwagger2 // 开启swagger2
public class Swagger2Config {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.fatal.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题:用户信息管理系统-接口文档")
.description("描述:about xxx")
.contact(new Contact("fatal", "fatal's url", "fatal's email"))
.version("1.0")
.build();
}

}

3、entity

swagger 提供了非常齐全的注解,为POJO提供了@ApiModel@ApiModelProperty,以便更好的渲染最终结果

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
package com.fatal.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;

/**
* User 实体
* @author: Fatal
* @date: 2018/10/17 0017 15:05
*/
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel
@Accessors(chain = true)
public class User {

private Long id;
@ApiModelProperty(name = "username", value = "用户名")
private String username;
@ApiModelProperty(name = "password", value = "密码")
private String password;

}

4、controller

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
35
36
37
38
39
40
41
42
43
44
package com.fatal.controller;

import com.fatal.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.Arrays;
import java.util.List;

/**
* User 控制器
* @author: Fatal
* @date: 2018/10/17 0017 15:07
*/
@RestController
@RequestMapping("/users")
public class UserController {

@GetMapping("/")
@ApiOperation(value = "查询所有", notes = "获取用户列表")
public List<User> get() {
List<User> users = Arrays.asList(new User(0L, "米彩", "123"),
new User(1L, "米琪", "123"));
return users;
}

@PostMapping("/")
@ApiOperation(value = "添加用户", notes = "添加用户操作")
public User insert(User user) {
return user;
}

@PutMapping("/")
@ApiOperation(value = "更新用户", notes = "更新用户操作")
public User update(@ApiParam(name = "id", value = "用户主键")
@RequestParam(name = "id") Long id) {
return new User()
.setId(id)
.setUsername("fatal")
.setPassword("123456");
}

}

5、显示

启动工程,打开浏览器输入 http://localhost:8080/swagger-ui.html 即可

1562028687002

1539779031489

注意

swagger 没有做安全方面的防护,可能需要我们自己做相关的工作。

6、笔记

注解描述

  • @Api: 描述Controller
  • @ApiIgnore: 忽略该Controller,指不对当前类做扫描
  • @ApiOperation: 描述Controller类中的method接口
  • @ApiParam: 描述单个入参信息,与@ApiImplicitParam不同的是,他是写在参数左侧的。如(@ApiParam(name = “username”,value = “用户名”) String username
  • @ApiModel: 描述POJO对象
  • @ApiModelProperty: 描述POJO对象中的属性值
  • @ApiImplicitParam: 描述单个入参信息,如果请求参数在url上,@ApiImplicitParam 上加paramType = “path”
  • @ApiImplicitParams: 描述多个入参信息
  • @ApiResponse: 描述单个出参信息
  • @ApiResponses: 描述多个出参信息
  • @ApiError: 接口错误所返回的信息

当我们指定了 Swagger 的扫描路径后,很多注解我们不写,它会取参数信息为默认值。

参考资料

SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

总结

SpringBoot的知识已经有前辈在我们之前探索了。比较喜欢的博主有:唐亚峰 | Battcn方志朋的专栏程序猿DD纯洁的微笑。对这门技术感兴趣的可以去他们的博客逛逛。谢谢他们的分享~~

以上文章是我用来学习的Demo,都是基于 SpringBoot2.x 版本。

源码地址: https://github.com/ynfatal/springboot2-learning/tree/master/chapter17_1

学习 唐亚峰方志朋 前辈的经验