SpringBoot整合Swagger

0. 前言

swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件,是一个规范和完整的框架。可十分高效的生成APi文档。

1. 依赖

需要引入io.springfox.springfox-swagger2和io.springfox.springfox-swagger-ui两个包。
maven版参考:

1
2
3
4
5
6
7
8
9
10
<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>

2. 配置

SpringBoot推荐使用Java配置类的形式配置Bean等。所以新建包config,新建类SwaggerConfig。示例代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//此处修改为你自己的controller包路径
.apis(RequestHandlerSelectors.basePackage("cn.hayye.springboot.swagger_demo.controller"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger案例Demo")
.description("Spring Boot整合swagger2")
.termsOfServiceUrl("https://github.com/hayye/swagger_demo")
.version("1.0")
.build();
}
}

3. 写文档

新建一个Controller,随便写一个接口,之后就是写注解了。

Swagger常用注解:

@Api:注解在类上,说明该类的作用;
@ApiOperation:注解在方法上,说明该方法的作用;
@ApiImplicitParam:说明该接口的一个参数;
@ApiImplicitParams:该接口的一组参数说明,可包含多个@ApiImplicitParam注解;
@ApiResponses:该接口响应的信息;
@ApiModel:描述一个Model的信息;

想要查看更详细的介绍点击:传送门

例子:

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
@RestController
@RequestMapping("/book")
@Api(value = "Book接口")
public class BookController {

@RequestMapping(value = "/price",method = RequestMethod.GET)
@ApiOperation(value="根据图书SN编码或书名获取图书价格", notes="返回JSON形式的图书属性包")
@ApiResponses({
@ApiResponse(code = 20000,message = "success"),
@ApiResponse(code=50000,message = "异常信息")
})
@ApiImplicitParams({
@ApiImplicitParam(paramType="query",name = "sn",value = "图书编号", required = false ,dataType = "String"),
@ApiImplicitParam(paramType="query",name = "bookname",value = "书名", required = false ,dataType = "String")
})
public AjaxResult getBookPrice(@RequestParam(name = "sn",required = false) String sn,
@RequestParam(name = "bookname",required = false)String bookname){
if (sn!=null && !sn.equals("")){
Book book = new Book(1,sn,"Java入门",88.88);
return new AjaxResult.Builder().code(20000).message("ok").data(book).build();
}
if (bookname!=null && !bookname.equals("")){
Book book = new Book(2,"0000000000",bookname,66.66);
return new AjaxResult.Builder().code(20000).message("ok").data(book).build();
}

return new AjaxResult.Builder().code(20000).message("输入参数不能全为空!").data(null).build();
}

@RequestMapping(value = "/all",method = RequestMethod.GET)
public AjaxResult getAllBook(){
List<Book> books = new ArrayList<>();
Book book1 = new Book(1,"0000000000","Java入门",88.88);
Book book2= new Book(2,"0000000001","Spring入门",66.66);
books.add(book1);
books.add(book2);
return new AjaxResult.Builder().code(20000).message("输入参数不能全为空!").data(books).build();
}
}

4. 进入swagger

启动你的项目,打开localhost:8080/swagger-ui.html
如果你设置的server-context,那么同理记得在连接里加上你的contextPath。
效果
效果图
好了,你所有的接口都在这里了,不仅能看,还能测试,点开一个接口,Try it out一下试试吧!

本案例源码已上传GitHub:传送门