Spring Boot 与 swagger
网上关于swagger 有着很多的介绍与使用帮助,因此本文将不会花费太多的笔墨去介绍swagger 是什么,它有什么好处,我们只需要知道swagger 可以为我们提供一个动态的可视化文档,所见即所得的更新我们的 API,并提供详细使用文档的一个工具就好了。
Spring Boot 集成 swagger
在项目的pom.xml文件中导入 swagger 的相关依赖:
1
2
3
4
5
6
7
8
9
10
11
<!--swagger -->
<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>
swagger相关包导入完成之后我们还需要专门为它写一个配置文件,用于设置一些个性化的相关内容,在项目工程中新建一个配置包,和一个配置文件SwaggerConfig.java,如图:
文件内容为:
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
/**
* @program: acgpicture
* @description: Swagger配置类
* @author: Mephisto
* @create: 2019-04-17 15:06
**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("团队名称")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("文档标题")
.contact(new Contact("联系人名称", "", "联系人邮箱(xxx@xxx.xxx)"))
.version("Api 版本").build();
}
}
不要忘记写注解,不然 Spring Boot 是不会帮我们加载该配置的,到这一步,swagger的配置就基本完成了,是不是很简单呢?然后我们运行起服务器来看一下吧!
启动服务器后浏览器中输入默认的网址:http://localhost:8080/swagger-ui.html,一切顺利的话可以看到这样的界面:
这样一来的话我们的swagger就算是集成成功了,下面让我们来使用它,看它怎样为我们的减少沟通成本,提升开发效率!
我们新建一个控制器包与一个主页类HomeController.java,将原来的 hello world 方法转移到该类下,代码如下:
1
2
3
4
5
6
7
8
@RestController
public class HomeController {
@GetMapping("/index")
String index() {
return "hello world";
}
}
需要注意的是@RestController是一个组合注解,包含@Controller:这是一个控制器,@ResponseBody:需要输出到浏览器这两个注解,而@GetMapping注解是@RequestMapping(method = RequestMethod.GET)的简写形式,当然,这两个复合注解都还包含其他的注解方法,不过我们现在只需要知道这一些就足够了,然后我们运行服务器,刷新swagger界面会发现我们的新请求就自动的出现在了这上面!
这就是swagger为我们带来的其中一个好处,实时更新,集成以后它会自动的去扫描我们的 Api,然后自动的更新文档,不需要我们再辛苦的手动写一份告诉前端某个接口是干什么的,这个接口需要哪些参数等等,swagger自动的为我们实现了这些,而我们只需要配置一下就好了
swagger常用注解
首先我们需要知道的是swagger是侵入式的框架,但是比起它能带给我们的便利性,这点小小的瑕疵还是可以接受的。swagger 常用的注解有@ApiOperation,@ApiImplicitParam,@Api这三个,@Api一般放在控制器上面,用于分组,@ApiOperation一般放在方法上面用于描述改接口的作用,@ApiImplicitParam通过名称可以知道是用于参数控制的,用来描述需要的参数和对其做一定的限定,比如:
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
@Api(tags = "用于 Api分组")
@RestController
public class HomeController {
@ApiOperation(value = "用于描述这个接口是干什么的")
@GetMapping("/index")
String index() {
return "hello world";
}
@ApiOperation(value = "通过用户 ID获取用户名")
@GetMapping(value = "/user/{id}")
@ApiImplicitParam(name = "id", value = "用户id")
String findUserByID(@PathVariable Long id) {
return "小明";
}
@ApiOperation(value = "通过用户名,班级获取用户")
@GetMapping(value = "/user", params = {"username", "classname"})
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = false),
@ApiImplicitParam(name = "classname", value = "班级名", required = false)
})
String findUserBy(String username, String classname) {
return "小明";
}
}
效果是这样的:
这个样子比起之间就更加的简单明了了,而且我们还可以直接在这这里测试接口,可以非常方便的对我们的 Api进行调试,到此,我们在 Spring Boot 中集成swagger差不多就完成了,当然,这里列举出来的东西仅仅是一些基础的使用,不过对于日常的文档编写应该还是足够的,还有一些进阶的使用方法会在以后的使用是慢慢记录出来。