（06）使用Swagger自动生成html文档，描述API接口

　　使用前后端分离，API文档必不可少，一旦代码变动，就要维护文档，很繁琐。Swagger根据代码自动实时生成文档，解决了这个问题。

　　1、演示Swagger使用过程

　　1）需要添加依赖

<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>

　　2）启动类添加注解@EnableSwagger2

@SpringBootApplication
@EnableSwagger2
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

　　3）添加测试类

@RestController
@RequestMapping("/user")
public class UserController {
    
    @GetMapping
    public List<User> query(User user){
        List<User> users = new ArrayList<User>();
        users.add(new User("1","张三","123456",new Date()));
        users.add(new User("2","李四","123422",new Date()));
        users.add(new User("3","王五","252153",new Date()));
        return users;
    }
    
    @GetMapping(value="/{id}")
    public User getUserInfo(@PathVariable("id") String id){
        User user=new User();
        user.setUsername("tom");
        return user;
    }

    @PostMapping
    public User create(@RequestBody User user){
        return new User("1","张三","123456",new Date());
    }
    
    @PutMapping("/{id:\\d+}")
    public User update(@RequestBody User user){
        return new User("1","张三","123456",new Date());
    }
    
    @DeleteMapping("/{id:\\d+}")
    public void delete(@PathVariable String id){
        System.out.println("id :"+id);
    }
}

public class User {

    private String id;
    private String username;
    private String password;
    private Date birthDay;
    
    public User() {}
    
    public User(String id,String username,String password,Date birthDay) {
        this.id=id;
        this.username=username;
        this.password=password;
        this.birthDay=birthDay;
    }
        
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
    public Date getBirthDay() {
        return birthDay;
    }
    public void setBirthDay(Date birthDay) {
        this.birthDay = birthDay;
    }
}

　　2、查看效果

　　1）启动服务，输入http://localhost/swagger-ui.html，显示如下，其中Basic Error Controller是Spring容器自带的。

　　

　　2）展开User Controller，可以看到定义的请求方式、url、方法名（默认显示java中的方法名）

　　

 　　3）展开一个方法，可以看到请求参数，并且可以执行Try it out真实的请求一次java方法，看返回什么。

　　

　　3、三个常用注解

　　1）注解说明

　　@EnableSwagger2：加在启动类上，表示使用wagger

　　@ApiOperation：加在方法上，显示自定义的方法名，如：@ApiOperation(value="查询用户列表")

　　@ApiParam：加在方法的参数前面，描述参数，如：@ApiParam("用户ID")

　　@ApiModelProperty：加在类的字段上，描述参数，如：@ApiModelProperty(value="用户名")

　　2）演示注解

@RestController
@RequestMapping("/user")
public class UserController {
    
    @GetMapping
    @ApiOperation(value="查询用户列表")
    public List<User> query(User user){
        List<User> users = new ArrayList<User>();
        users.add(new User("1","张三","123456",new Date()));
        users.add(new User("2","李四","123422",new Date()));
        users.add(new User("3","王五","252153",new Date()));
        return users;
    }
    
    @GetMapping(value="/{id}")
    @ApiOperation(value="根据ID查询用户")  
    public User getUserInfo(@ApiParam("用户ID") @PathVariable("id") String id){
        User user=new User();
        user.setUsername("tom");
        return user;
    }

    @PostMapping
    @ApiOperation(value="创建用户")
    public User create(@RequestBody User user){
        return new User("1","张三","123456",new Date());
    }
    
    @PutMapping("/{id:\\d+}")
    @ApiOperation(value="修改用户")
    public User update(@RequestBody User user){
        return new User("1","张三","123456",new Date());
    }
    
    @DeleteMapping("/{id:\\d+}")
    @ApiOperation(value="删除用户")
    public void delete(@PathVariable String id){
        System.out.println("id :"+id);
    }
}

public class User {

    @ApiModelProperty(value="用户Id")
    private String id;
    @ApiModelProperty(value="用户名")
    private String username;
    @ApiModelProperty(value="用户密码")
    private String password;
    @ApiModelProperty(value="出生日期")
    private Date birthDay;
    
    public User() {}
    
    public User(String id,String username,String password,Date birthDay) {
        this.id=id;
        this.username=username;
        this.password=password;
        this.birthDay=birthDay;
    }
        
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
    public Date getBirthDay() {
        return birthDay;
    }
    public void setBirthDay(Date birthDay) {
        this.birthDay = birthDay;
    }
}

　　3）效果如下：