springboot集成swagger2构建RESTful API文档

在开发过程当中,有时候咱们须要不停的测试接口,自测,或者交由测试测试接口,咱们须要构建一个文档,都是单独写,太麻烦了,如今使用springboot集成swagger2来构建RESTful API文档,能够在访问接口上,直接添加注释

 

先介绍一下开发环境:

1. jdk版本是1.8
2. springboot的版本是1.4.1
3. 开发工具为 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"; } }

 

大家别吐槽个人方法命名........将就着看吧...测试demo,命名随意了些(实际上是我英语不太好....哈哈哈哈哈.....)

 

写好controller后,咱们能够访问如下地址:http://localhost:8080/swagger-ui.html,若是你没引入swagger2依赖,你是访问不了的..而后你会获得一个以下页面

 

上面的页面,就是swagger2里面的页面,能够发现, apiInfo里面设置的内容在左边展现出来了,demo-application其实就是controller的类名,右边有三个按钮,分别是 Show/Hide,List Opertions和Expand Operations,三个按钮均可以打开,类下的接口,点击后,会获得以下一个效果页面:

能够发现,展现出来了,controller下的三个接口(其实有四个,只不过有一个咱们用注解忽略了,在这不展现而已..)

 

上面三个接口,在咱们注解里面添加的,都有展现,请求方式,接口名称,如今咱们打开某个接口,看看具体内容,接口内的内容,我不在用文字描述,我直接在截图里面添加描述了.见谅....

 

这个,,截图比较烂,各位将就着看吧..别嫌弃...,咱们点击try it out 按钮,就会发送请求,结果以下:

 

以上就是比较简单的demo测试文档啦,若是各位想配置更详细,就去官网看吧..地址我贴出来:

swagger官网地址:http://swagger.io/

 

下面就是介绍,上面接口中,上面关于swagger2本人经常使用注解的一些描述

 

 

本人经常使用注解说明：

@ApiOperation：用在方法上，说明方法的做用

1.     value: 表示接口名称
2.     notes: 表示接口详细描述 

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

1. paramType：参数位置

• header 对应注解：@RequestHeader
• query 对应注解：@RequestParam
• path  对应注解: @PathVariable
• body 对应注解: @RequestBody

1. name：参数名
2. dataType：参数类型
3. required：参数是否必须传
4. value：参数的描述
5. defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，通常用于表达一个错误的响应信息

1. code：状态码
2. message：返回自定义信息
3. response：抛出异常的类

@ApiIgnore: 表示该接口函数不对swagger2开放展现

以上这些就是我测试过的注解,并无深究,有兴趣的,能够看看其它注解,或者源码,会比我描述的全不少,

 

对了,须要注意下,@ApiImplicitParam注解下的paramType属性,会影响接口的测试,若是设置的属性跟spring的注解对应不上,会获取不到参数,例如:paramType=path,函数内却使用@RequestParam注解,这样,可能会获取不到传递进来的参数,须要按照上面进行对应,将@RequestParam注解改成@PathVariable才能获取到对应的参数...