zoukankan      html  css  js  c++  java
  • (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)效果如下:

      

      

      

      

      

      

      

  • 相关阅读:
    8.20 附加赛3
    8.22 附加赛4
    Codeforces Round #505 (Div 1 + Div 2) (A~D)
    8.9 附加赛2
    8.10 正睿暑期集训营 Day7
    8.9 正睿暑期集训营 Day6
    8.8 正睿暑期集训营 Day5
    8.7 正睿暑期集训营 Day4
    8.6 正睿暑期集训营 Day3
    8.5 正睿暑期集训营 Day2
  • 原文地址:https://www.cnblogs.com/javasl/p/12993021.html
Copyright © 2011-2022 走看看