springboot+swagger2说明

swagger用于定义API文档。

优势：

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件

添加pom依赖

<!--swagger2 start-->
<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>
<!--swagger2 end-->

Swagger2Config初始化配置如下：

[java] view plain copy

1. package com.gasq.travel.config;  
2.   
3. import com.gasq.travel.common.CodeEnum;  
4. import com.gasq.travel.utils.collections.ListUtils;  
5. import io.swagger.annotations.ApiOperation;  
6. import org.springframework.beans.factory.annotation.Value;  
7. import org.springframework.boot.context.properties.ConfigurationProperties;  
8. import org.springframework.context.annotation.Bean;  
9. import org.springframework.context.annotation.Configuration;  
10. import org.springframework.web.bind.annotation.RequestMethod;  
11. import org.springframework.web.context.request.async.DeferredResult;  
12. import springfox.documentation.builders.ApiInfoBuilder;  
13. import springfox.documentation.builders.PathSelectors;  
14. import springfox.documentation.builders.RequestHandlerSelectors;  
15. import springfox.documentation.builders.ResponseMessageBuilder;  
16. import springfox.documentation.schema.ModelRef;  
17. import springfox.documentation.service.ApiInfo;  
18. import springfox.documentation.service.ResponseMessage;  
19. import springfox.documentation.spi.DocumentationType;  
20. import springfox.documentation.spring.web.plugins.Docket;  
21. import springfox.documentation.swagger2.annotations.EnableSwagger2;  
22.   
23. import java.util.List;  
24.   
25. /** 
26.  * @description: swagger2配置文件类 
27.  * @访问路径： 如 http://localhost:8080/swagger-ui.html 
28.  * @author fanpeng 
29.  * @create 2017-01-03 10:00 
30.  * @Modify By: 
31.  **/  
32. @Configuration  
33. @EnableSwagger2  
34. @ConfigurationProperties  
35. public class Swagger2Config {  
36.     @Value("${swagger.version}") private String version;  
37.     @Value("${swagger.basePackage}") private String basePackage;  
38.   
39.     @Bean  
40.     public Docket createRestApi() {  
41.         return new Docket(DocumentationType.SWAGGER_2)  
42.                 .apiInfo(apiInfo())  
43.                 .groupName("travel")  
44.                 .genericModelSubstitutes(DeferredResult.class)  
45.                 .useDefaultResponseMessages(false)  
46.                 .globalResponseMessage(RequestMethod.GET,customerResponseMessage())  
47.                 .forCodeGeneration(true)  
48.                 .select()  
49.                 .apis(RequestHandlerSelectors.basePackage(basePackage))  
50.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  
51.                 .paths(PathSelectors.any())  
52.                 .build();  
53.     }  
54.   
55.     private ApiInfo apiInfo() {  
56.         return new ApiInfoBuilder()  
57.                 .title("国安社区-travel接口")  
58.                 .description("I'm description..")  
59.                 .contact("东哥")  
60.                 .version(version)  
61.                 .license("国安社区")  
62.                 .licenseUrl("baidu.com")  
63.                 .build();  
64.     }  
65.   
66.     /** 
67.      * 自定义返回信息 
68.      * @param 
69.      * @return 
70.      */  
71.     private List<ResponseMessage> customerResponseMessage(){  
72.         return ListUtils.convertToList(  
73.                 new ResponseMessageBuilder()//500  
74.                         .code(CodeEnum.error.getValue())  
75.                         .message(CodeEnum.error.getDescription())  
76.                         .responseModel(new ModelRef("Error"))  
77.                         .build(),  
78.                 new ResponseMessageBuilder()//401  
79.                         .code(CodeEnum.paramError.getValue())  
80.                         .message(CodeEnum.paramError.getDescription())  
81.                         .build());  
82.     }  
83.   
84.   
85. }  

Controller中测试方法：

在这里我们使用@ApiOperation注解来声明此方法为要生成的接口文档，在配置中已经配置过了，如果不想方法生成文档，不加此注解即可；

配置中已经使用了自定义的响应信息，所以可以不设置@ApiResponses；

[java] view plain copy

1.     @ApiOperation(value="测试日志程序", notes="测试日志程序", produces = "application/json")  
2.     @ApiImplicitParams(value = {  
3.             @ApiImplicitParam(name = "school", value = "学校名称", required = true, paramType = "query", dataType = "String"),  
4.             @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String")  
5.     })  
6.     @RequestMapping(value = "/get",method = RequestMethod.GET)  
7.     public void testProgram(HttpServletRequest request, HttpServletResponse response){  
8.         logger.debug("debug");  
9.         logger.info("info");  
10.         logger.error("error");  
11.         logger.warn("warn");  
12.   
13.         Student student = studentCommandService.selectById(1);  
14. //        Student student = studentCommandService.queryById(1l);  
15.         System.out.println(student.toString());  
16.         this.renderJson(CodeEnum.success.getValue(),CodeEnum.success.getDescription(),student,request,response);  
17.     }  

注解说明：

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  • paramType：参数放在哪个地方
    • header-->请求参数的获取：@RequestHeader
    • query-->请求参数的获取：@RequestParam
    • path（用于restful接口）-->请求参数的获取：@PathVariable
    • body（不常用）
    • form（不常用）
  • name：参数名
  • dataType：参数类型
  • required：参数是否必须传
  • value：参数的意思
  • defaultValue：参数的默认值
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类
• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  • @ApiModelProperty：描述一个model的属性

以上这些就是最常用的几个注解了。

需要注意的是：

• ApiImplicitParam这个注解不只是注解，还会影响运行期的程序，例子如下：

　　

如果ApiImplicitParam中的phone的paramType是query的话，是无法注入到rest路径中的，而且如果是path的话，是不需要配置ApiImplicitParam的，即使配置了，其中的value="手机号"也不会在swagger-ui展示出来。

 

具体其他的注解，查看：

https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

生成文档效果： 果

方法效果：

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，就能看到上文所展示的RESTful API的页面。