Spring Boot RESTful 在线API文档

使用Spring Boot 去开发一个RESTful API是一件简单的事情,而且Spring Boot结合Swagger后,使用注解就能简单的实现在线API文档,这样能实现修改代码和修改文档二合一,降低开发人员造成文档和接口的不一致的几率。以下为具体实现。

引入swagger的相关依赖

1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

编写swagger配置类

swagger的配置类可以放在Spring Boot入口类的旁边

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.lefer.demo4doc.controller"))//要扫描的API(Controller)基础包
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title("CDR在线文档") // 在线API文档的标题
.contact("winning") // 在线API文档的作者
.version("0.1") // 在线API文档的版本号
.build();
}
}

在api接口上添加注解

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
45
46
47
@Api(value = "字符串处理服务",description = "简单的字符串处理,提供截取、替换、查询API")
@RestController
@RequestMapping(path = "/api")
public class ApiController {
@ApiOperation(value = "截取字符串")
@RequestMapping(path = "/substr",method = RequestMethod.POST)
public Result subStr(@ApiParam(required = true,value = "待处理字符串") @RequestParam String str,
@ApiParam(required = true,value = "截取开始位置") @RequestParam int from,
@ApiParam(required = true,value = "截取结束位置") @RequestParam int to) {
return ResultGenerator.genSuccessResult(str.substring(from,to));
}
@ApiOperation(value = "连接字符串")
@RequestMapping(path = "/joinstr",method = RequestMethod.POST)
public Result joinStr(@ApiParam(required = true,value = "待处理字符串") @RequestParam String str1,
@ApiParam(required = true,value = "需连接字符串") @RequestParam String str2) {
return ResultGenerator.genSuccessResult(str1.concat(str2));
}
@ApiIgnore
@RequestMapping(path="/giveback",method = RequestMethod.POST)
public Object giveBack(){
Article article = new Article();
article.setId("123");
article.setTitle("test");
article.setContent("hahahatest");
try{
CustomerJsonSerializer cjs = new CustomerJsonSerializer();
cjs.filter(Article.class,null,"title");
String result = cjs.toJson(article);
return result;
}catch (Exception e){
}
return article;
}
@ApiIgnore
@JsonView(View.Summary2.class)
@RequestMapping(path="/test",method = RequestMethod.POST)
public Result test(){
Article article = new Article();
article.setId("123");
article.setTitle("test");
article.setContent("hahahatest");
return ResultGenerator.genSuccessResult(article);
}
}

核心的的注解有以下几个

@Api 注解在Class上,用以描述整个类的功能

@ApiOperation 注解在方法上,用以描述API方法的功能

@ApiParam 注解在方法的入参上,用以描述入参,如果是必需的参数,可以用required = true标明

@ApiIgnore 注解在方法上,指示swagger忽略该api

出参的注解需要注解到响应类上,比如以上的代码中都是通过Result类去响应请求的,对应Result类上的代码:

1
2
3
4
5
6
7
8
9
10
@ApiModel("统一响应模型")
public class Result {
@ApiModelProperty("响应状态")
private int status;
@ApiModelProperty("响应消息")
private String message;
@ApiModelProperty("响应数据")
private Object data;
//省略 getter setter
}

核心的的注解有以下几个

@ApiModel 注解在模型类上,描述类

@ApiModelProperty 注解在属性上,用于描述属性

至此,大功告成,运行工程,访问 http://localhost:port/swagger-ui.html 即可查看效果

展现效果

  • API DOC 首页

自动生成API列表

  • 具体的每一个API的说明

API界面

  • 还提供了API在线调试的功能,try it

在线调试

END