Swgger2的简单使用

编写接口文档是一个非常枯燥的工作，我们采用Swagger2这套自动化文档工具来生成文档，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。

1、在pom.xml文件中加入Swagger2的依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、创建Swagger2配置类

 1 package com.offcn.springbootdemo2.Config;
 2 
 3 import org.springframework.context.annotation.Bean;
 4 import org.springframework.context.annotation.Configuration;
 5 import springfox.documentation.builders.ApiInfoBuilder;
 6 import springfox.documentation.builders.PathSelectors;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.service.ApiInfo;
 9 import springfox.documentation.spi.DocumentationType;
10 import springfox.documentation.spring.web.plugins.Docket;
11 import springfox.documentation.swagger2.annotations.EnableSwagger2;
12 
13 @Configuration
14 @EnableSwagger2
15 public class SwaggerConfig {
16 
17    @Bean
18    public Docket createRestApi(){
19       return new Docket(DocumentationType.SWAGGER_2)
20             .apiInfo(apiInfo())
21             .select().apis(RequestHandlerSelectors.basePackage("com.offcn.springbootdemo2.Controller"))
22             .paths(PathSelectors.any()).build();
23    }
24 
25    private ApiInfo apiInfo() {
26       return new ApiInfoBuilder().title("RestFul风格").description("一种好的习惯")
27             .termsOfServiceUrl("http://www.baidu.com").contact("java").version("1.0").build();
28    }
29 }

3、修改Controller增加文档注释

 1 package com.offcn.springbootdemo2.Controller;
 2 
 3 import com.offcn.springbootdemo2.Pojo.User;
 4 import io.swagger.annotations.ApiImplicitParam;
 5 import io.swagger.annotations.ApiImplicitParams;
 6 import io.swagger.annotations.ApiOperation;
 7 import org.springframework.web.bind.annotation.*;
 8 
 9 import java.util.ArrayList;
10 import java.util.Collections;
11 import java.util.List;
12 
13 @RestController
14 @RequestMapping("/user")
15 public class UserController {
16 
17    private List<User> listUser= Collections.synchronizedList(new ArrayList<User>());
18    @GetMapping("/")
19    public List<User> getUserList(){
20       return listUser;
21    }
22 
23    /***
24     * 新增用户
25     * @param user
26     * @return
27     */
28    @PostMapping("/")
29    public String createUser(User user) {
30       listUser.add(user);
31       return "success";
32    }
33 
34    /***
35     * 获取指定id用户信息
36     * @param id
37     * @return
38     */
39    @GetMapping("/{id}")
40 
41    public User getUser(@PathVariable("id") Integer id) {
42       for (User user : listUser) {
43          if(user.getId()==id) {
44             return user;
45          }
46       }
47       return null;
48    }
49    /**
50     * 更新指定id用户信息
51     * @param id
52     * @param user
53     * @return
54     */
55    @PutMapping("/{id}")
56    @ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")
57    @ApiImplicitParams({
58          @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
59          @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
60    })
61    public String updateUser(@PathVariable("id") Integer id,User user) {
62       for (User user2 : listUser) {
63          if(user2.getId() == id) {
64             user2.setName(user.getName());
65             user2.setAge(user.getAge());
66          }
67       }
68       return "success";
69    }
70 
71    /***
72     * 删除指定id用户
73     * @param id
74     * @return
75     */
76    @DeleteMapping("/{id}")
77    @ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")
78    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
79    public String deleteUser(@PathVariable("id") Integer id) {
80 
81       listUser.remove(getUser(id));
82       return "success";
83 
84    }
85 }

4、启动项目，在浏览器地址输入

http://localhost:8080/swagger-ui.html

查看Swagger2文档

额外添加一个依赖Lombok，可以省略实体类中繁琐的代码

<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.10</version>
    <scope>provided</scope>
</dependency>