（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）效果如下：