情景简述
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释就能实现
开发环境
先介绍一下开发环境:
- jdk版本是1.8
- springboot的版本是1.4.1
- 开发工具为 intellij idea
我们先引入swagger2的jar包,pom文件引入依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
使用实例
接下来,我们构建swagger2的配置类,代码如下:
//注解开启 swagger2 功能
@EnableSwagger2
//注解标示,这是一个配置类,@Configuation注解包含了@Component注解
//可以不用在使用@Component注解标记这是个bean了,
@Configuration
public class Swagger2 {
/**
* 通过 createRestApi函数来构建一个DocketBean
* 函数名,可以随意命名,喜欢什么命名就什么命名
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
.select()
//控制暴露出去的路径下的实例
//如果某个接口不想暴露,可以使用以下注解
//@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
//创建人
.contact("贺小五")
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
swagger2的配置类已经配置好了,下面,我们就在主函数里面随意写一些接口吧
@SpringBootApplication(scanBasePackages = {"com"})
//该注解包含了@Controller和@ResponseBody两个注解
@RestController
public class DemoApplication{
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
/**
* 以下函数的注释,不增加注解了,将在下面统一做描述
*/
@ApiOperation(value = "测试post请求",notes="注意事项")
@ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true)
@RequestMapping(value = "/testPost",method = RequestMethod.POST)
public String testPost(@RequestBody User user){
return "success";
}
@ApiOperation(value = "测试get请求",notes="注意事项")
@ApiImplicitParam(name = "id",value = "用户id",dataType = "String",paramType = "path")
@RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET)
public String testGet(@PathVariable String id){
return id;
}
@ApiOperation(value = "测试组合注解",notes="注意事项")
@ApiImplicitParams({
@ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true,paramType = "body"),
@ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true,paramType = "path")
})
@RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST)
public User joinAnnotation(@PathVariable String id,@RequestBody User user){
return user;
}
@ApiIgnore
public String testIgnore(){
return "success";
}
}
写好controller后,我们可以访问以下地址:http://localhost:8080/swagger-ui.html,如果你没引入swagger2依赖,你是访问不了的..然后你会得到一个如下页面
上面的页面,就是swagger2里面的页面,可以发现, apiInfo里面设置的内容在左边展示出来了,demo-application其实就是controller的类名,右边有三个按钮,分别是 Show/Hide,List Opertions和Expand Operations,三个按钮都可以打开,类下的接口,点击后,会得到如下一个效果页面:
可以发现,展示出来了,controller下的三个接口(其实有四个,只不过有一个我们用注解忽略了,在这不展示而已..)
上面三个接口,在我们注解里面添加的,都有展示,请求方式,接口名称,现在我们打开某个接口,看看具体内容,接口内的内容,我不在用文字描述,我直接在截图里面添加描述了.见谅....
我们点击try it out 按钮,就会发送请求,结果如下:
swagger官网地址:http://swagger.io/
重要参数
下面就是介绍,上面接口中,上面关于swagger2本人常用注解的一些描述
本人常用注解说明：
@ApiOperation：用在方法上，说明方法的作用
value: 表示接口名称
notes: 表示接口详细描述
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数位置
header 对应注解：@RequestHeader
query 对应注解：@RequestParam
path 对应注解: @PathVariable
body 对应注解: @RequestBody
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的描述
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：状态码
message：返回自定义信息
response：抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
注意事项
以上这些就是我测试过的注解,并没有深究,有兴趣的,可以看看其它注解,或者源码,会比我描述的全很多,
对了,需要注意下,@ApiImplicitParam注解下的paramType属性,会影响接口的测试,如果设置的属性跟spring的注解对应不上,会获取不到参数,例如:paramType=path,函数内却使用@RequestParam注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将@RequestParam注解改为@PathVariable才能获取到对应的参数...
