(06)使用Swagger自动生成html文档,描述API接口

时间:2020-05-30
本文章向大家介绍(06)使用Swagger自动生成html文档,描述API接口,主要包括(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)效果如下:

  

  

  

 

 

  

  

  

 

  

$flag 上一页 下一页