由于 Spring Boot 能够快速开发、便捷部署等特性， 通常在使用 Spring Boot构建 Restful 接口应用时考虑到多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者 Web 前端。对于不同的终端公用一套接口 Api 时对于联调测试时就需要知道后端提供的接口Api列表文档，对于服务端开发人员来说就需要编写接口文档，描述接口调用地址参数 结果等，这里借助第三方构建工具Swagger2来实现Api文档生成功能。

  • 添加依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
  • 配置文件
 1 @Configuration
 2 @EnableSwagger2
 3 public class Swagger2Config {
 4     @Bean
 5     public Docket customDocket() {
 6         return new Docket(DocumentationType.SWAGGER_2)
 7                 .apiInfo(apiInfo())
 8                 .select()
 9                 .apis(RequestHandlerSelectors.any())
10                 .paths(PathSelectors.any())
11                 .build();
12     }
13 
14     private ApiInfo apiInfo() {
15         Contact contact = new Contact("团队名", "www.my.com", "my@my.com");
16         return new ApiInfoBuilder()
17                 .title("文档标题")
18                 .description("文档描述")
19                 .contact(contact)   // 联系方式
20                 .version("1.1.0")  // 版本
21                 .build();
22     }
23 }
  • 控制层
 1 @Api(tags = "样例接口")
 2 @RestController
 3 public class DemoController {
 4 
 5 
 6     @ApiOperation(value = "插入demo")
 7     @PutMapping("putDemo")
 8     public Map<String,Object> putDemo() {
 9         System.out.println("执行插入数据");
10         Map<String,Object> map = new HashMap<>();
11         map.put("code",200);
12         map.put("msg","success");
13         return map;
14     }
15 
16     @ApiOperation(value = "查询demo")
17     @ApiImplicitParam(dataType = "integer",defaultValue = "",required = true)
18     @GetMapping("/getDemo/{userId}")
19     public List<String> getDemo(@PathVariable Integer userId) {
20         List<String> list = new ArrayList<>();
21         list.add("OK");
22         return list;
23     }
24 }

 

　　访问浏览器,输入http://localhost:8088/swagger-ui.html

 

常用注解解释说明：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiImplicitParams：多个请求参数
@ApiImplicitParam：一个请求参数
@ApiResponses：HTTP响应整体描述
@ApiResponse：HTTP响应其中1个描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API