【SpringBoot框架篇】17.使用swagger2生成RESTful风格的接口文档

快来打我* 2023-03-04 06:59 26阅读 0赞

### 文章目录 ###

*  简介
 *  实战应用
 *   *  引入相关依赖
     *  swagger配置
     *   *  application.yml配置文件
         *  swagger配置类
     *  注解描述
     *   *  API接口注解
         *   *  常用注解
             *  @ApiImplicitParam参数说明
             *  测试用例
         *  模型类注解
         *   *  常用注解
             *  测试用例
 *  查看API接口文档
 *   *  访问接口文档页面
     *  查看添加用户接口描述
     *  查看模型类描述
 *  解决ApiModel类作为属性返回没有显示类描述
 *   *  改造上面的HttpResult数据返回封装类
     *   *  添加\`\`让类变成泛型类
         *  设置data为泛型属性
         *  接口返回的时候指定返回类型
     *  查看效果
 *  项目配套代码

# 简介 #

现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，  
但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

# 实战应用 #

## 引入相关依赖 ##

<properties>
            <swagger.version>2.9.2</swagger.version>
     </properties>
        
     <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>
     </dependencies>

## swagger配置 ##

### application.yml配置文件 ###

#生产环境改成false禁用
    server:
     port: 8017
    swagger:
      enable: true

### swagger配置类 ###

*  @ConditionalOnProperty 注解用于动态加载配置类

*  通过其两个属性name以及havingValue来实现的，其中name用来从application.properties中读取某个属性值。
 *  如果该值为空，则返回false;
 *  如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true;否则返回false。
 *  如果返回值为false，则该configuration不生效(不会加载该类)；为true则生效。

@Configuration
    @EnableSwagger2
    @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
    public class SwaggerConfig { 
    
        /** * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等 * @return Docket */
        @Bean(value = "defaultApi")
        public Docket defaultApi() { 
            //添加header参数
            ParameterBuilder ticketPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<>();
            ticketPar.name("token")
                    .description("用户登录获取的token信息")
                    .modelRef(new ModelRef("string")).parameterType("header")
                    //header中的参数是非必填的。
                    .required(false).build();
            pars.add(ticketPar.build());
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    // 为当前包路径
    	                .apis(RequestHandlerSelectors.basePackage("com.ljm.boot.swagger"))
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build()
                    .groupName("需要token验证")
                    .globalOperationParameters(pars);
        }
    
    
        /** * api文档的详细信息函数,注意这里的注解引用的是哪个 */
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    // //大标题
                    .title("【SpringBoot框架篇】 17.swagger对接口文档进行管理")
                    // 版本号
                    .version("1.0")
                   .termsOfServiceUrl("NO terms of service")
                    // 描述
                    .description("本教程配套代码github地址:https://github.com/Dominick-Li/springboot-master")
                    //作者
                    .license("The Apache License, Version 2.0")
                    .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                    .build();
        }
    }

## 注解描述 ##

### API接口注解 ###

#### 常用注解 ####

*  @Api : 用在类上，描述该类的主要作用。
 *  @ApiOperation：用在方法上，描述该方法主要作用。
 *  @ApiImplicitParams : 用在方法上，包含一组参数说明。
 *  @ApiImplicitParam: 用在方法上，用于描述一个参数说明

#### @ApiImplicitParam参数说明 ####

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>参数的描述信息</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>默认值</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>必选？ (默认值false) ,设置true该参数必须填写</td> 
  </tr> 
 </tbody> 
</table>

#### 测试用例 ####

@RestController
    @Api(tags = "用户管理相关接口")
    @RequestMapping("/user")
    public class UserController { 
    
      @GetMapping("/")
      @ApiOperation("分页查询所有用户")
      public List<User> getUserById(@RequestBody PageParam pageParam) { 
          return new ArrayList<User>();
      }
    
      @GetMapping("/{id}")
      @ApiOperation("根据id查询用户的接口")
      @ApiImplicitParam(name = "id", value = "用户id", required = true)
      public User getUserById(@PathVariable Integer id) { 
         return new User();
      }
    
    
      @PostMapping("/")
      @ApiOperation("添加用户的接口")
      @ApiImplicitParams({ 
              @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
              @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "北京", required = true)
      })
      public HttpResult addUser(String username, @RequestParam(required = true) String address) { 
          return HttpResult.successResult();
      }
    
      @PutMapping("/{id}")
      @ApiOperation("根据id更新用户的接口")
      public HttpResult updateUserById(@RequestBody User user) { 
          return HttpResult.successResult();
      }
    
    }

### 模型类注解 ###

#### 常用注解 ####

*  @ApiModel 描述该类的信息
 *  @ApiModelProperty 描述该属性的信息

#### 测试用例 ####

@ApiModel("用户类")
    public class User { 
        @ApiModelProperty("用户唯一id")
        private Integer id;
    
        @ApiModelProperty("用户名")
        private String username;
    
        @ApiModelProperty("密码")
        private String password;
    
        @ApiModelProperty("地址")
        private String address;
        //省略get set方法
    } 
    @ApiModel("Http结果响应")
    public class HttpResult  implements Serializable { 
    
        private static String successMessage = "操作成功";
    
        private static String errorMessage = "操作失败";
    
        @ApiModelProperty("响应码")
        private int code;
    
        @ApiModelProperty("响应数据")
        private Object data;
    
        @ApiModelProperty("响应消息")
        private String msg;
    
        public HttpResult(){  }
    
        public HttpResult(int code, String msg) { 
            this.code=code;
            this.msg=msg;
        }
    
        public HttpResult(int code, String msg, Object data) { 
            this.code=code;
            this.msg=msg;
            this.data=data;
        }
    
        public int getCode() { 
            return code;
        }
    
        public void setCode(int code) { 
            this.code = code;
        }
    
        public Object getData() { 
            return data;
        }
    
        public void setData(Object data) { 
            this.data = data;
        }
    
        public String getMsg() { 
            return msg;
        }
    
        public void setMsg(String msg) { 
            this.msg = msg;
        }
    
        public static HttpResult successResult() { 
            return new HttpResult(HttpStatus.OK.value(), successMessage);
        }
    
        public static HttpResult successResult(String msg) { 
            return new HttpResult(HttpStatus.OK.value(), defaultSuccessMsg(msg));
        }
    
        public static HttpResult successResult(Object obj) { 
            return new HttpResult(HttpStatus.OK.value(), successMessage, obj);
        }
    
        public static HttpResult successResult(String msg, Object obj) { 
            return new HttpResult(HttpStatus.OK.value(), defaultSuccessMsg(msg), obj);
        }
    
        public static HttpResult failureResult() { 
            return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), errorMessage);
        }
    
        public static HttpResult failureResult(String msg) { 
            return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), defautlErrorMsg(msg));
        }
    
        public static HttpResult failureResult(Integer code, String msg) { 
            return new HttpResult(code, defautlErrorMsg(msg));
        }
    
        public static HttpResult failureResult(String msg, Object obj) { 
            return new HttpResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), defaultSuccessMsg(msg), obj);
        }
    
        private static String defautlErrorMsg(String msg) { 
            return StringUtils.isEmpty(msg)?errorMessage:msg;
    
        }
    
        private static String defaultSuccessMsg(String msg) { 
            return StringUtils.isEmpty(msg)?successMessage:msg;
        }
    }

# 查看API接口文档 #

## 访问接口文档页面 ##

访问http://localhost:8017/swagger-ui.html查看API接口文档  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70]

## 查看添加用户接口描述 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 1]

## 查看模型类描述 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 2]

# 解决ApiModel类作为属性返回没有显示类描述 #

## 改造上面的HttpResult数据返回封装类 ##

### 添加`<T>`让类变成泛型类 ###

@ApiModel("Http结果响应")
    public class HttpResult<T> implements Serializable { }

### 设置data为泛型属性 ###

@ApiModelProperty("响应数据")
        private T data;
        public T getData() { 
            return data;
        }
    
        public void setData(T data) { 
            this.data = data;
        }

### 接口返回的时候指定返回类型 ###

@GetMapping("/{id}")
     public HttpResult<User> getUserById(@PathVariable Integer id) { 
           return HttpResult.successResult(new User());
     }

## 查看效果 ##

重新启动项目查看接口描述,看到data属性里已经变成了ApiModel类了。

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 3]

# 项目配套代码 #

[github地址][github]

创作不易,要是觉得我写的对你有点帮助的话,麻烦在github上帮我点下 **Star**

【SpringBoot框架篇】其它文章如下,后续会继续更新。

*  [1.搭建第一个springboot项目][1._springboot]
 *  [2.Thymeleaf模板引擎实战][2.Thymeleaf]
 *  [3.优化代码,让代码更简洁高效][3.]
 *  [4.集成jta-atomikos实现分布式事务][4._jta-atomikos]
 *  [5.分布式锁的实现方式][5.]
 *  [6.docker部署,并挂载配置文件到宿主机上面][6.docker]
 *  [7.项目发布到生产环境][7.]
 *  [8.搭建自己的spring-boot-starter][8._spring-boot-starter]
 *  [9.dubbo入门实战][9.dubbo]
 *  [10.API接口限流实战][10.API]
 *  [11.Spring Data Jpa实战][11.Spring Data Jpa]
 *  [12.使用druid的monitor工具查看sql执行性能][12._druid_monitor_sql]
 *  [13.使用springboot admin对springboot应用进行监控][13._springboot admin_springboot]
 *  [14.mybatis-plus实战][14.mybatis-plus]
 *  [15.使用shiro对web应用进行权限认证][15._shiro_web]
 *  [16.security整合jwt实现对前后端分离的项目进行权限认证][16.security_jwt]
 *  [17.使用swagger2生成RESTful风格的接口文档][17._swagger2_RESTful]
 *  [18.使用Netty加websocket实现在线聊天功能][18._Netty_websocket]
 *  [19.使用spring-session加redis来实现session共享][19._spring-session_redis_session]
 *  [20.自定义@Configuration配置类启用开关][20._Configuration]
 *  [21.对springboot框架编译后的jar文件瘦身][21._springboot_jar]
 *  [22.集成RocketMQ实现消息发布和订阅][22._RocketMQ]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70]: /images/20230208/a7593f1c31ab4f94ad53daee6b0d8e15.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 1]: /images/20230208/2a8fe9fbc92c412b960da10dc666a757.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 2]: /images/20230208/deb0a857a54148d5b407ff7d38230233.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmcxOTk1MTIyNA_size_16_color_FFFFFF_t_70 3]: /images/20230208/7936d963e6304bbcaf8d7f7d0d1e2001.png
[github]: https://github.com/Dominick-Li/springboot-master
[1._springboot]: https://blog.csdn.net/ming19951224/article/details/106159309
[2.Thymeleaf]: https://blog.csdn.net/ming19951224/article/details/106160322
[3.]: https://blog.csdn.net/ming19951224/article/details/106173840
[4._jta-atomikos]: https://blog.csdn.net/ming19951224/article/details/105753333
[5.]: https://blog.csdn.net/ming19951224/article/details/106205332
[6.docker]: https://blog.csdn.net/ming19951224/article/details/105923548
[7.]: https://blog.csdn.net/ming19951224/article/details/106212271
[8._spring-boot-starter]: https://blog.csdn.net/ming19951224/article/details/106224172
[9.dubbo]: https://blog.csdn.net/ming19951224/article/details/106225928
[10.API]: https://blog.csdn.net/ming19951224/article/details/106227451
[11.Spring Data Jpa]: https://blog.csdn.net/ming19951224/article/details/106308544
[12._druid_monitor_sql]: https://blog.csdn.net/ming19951224/article/details/106317893
[13._springboot admin_springboot]: https://blog.csdn.net/ming19951224/article/details/107138845
[14.mybatis-plus]: https://blog.csdn.net/ming19951224/article/details/107145780
[15._shiro_web]: https://blog.csdn.net/ming19951224/article/details/107192585
[16.security_jwt]: https://blog.csdn.net/ming19951224/article/details/107733689
[17._swagger2_RESTful]: https://blog.csdn.net/ming19951224/article/details/107741541
[18._Netty_websocket]: https://blog.csdn.net/ming19951224/article/details/108555917
[19._spring-session_redis_session]: https://blog.csdn.net/ming19951224/article/details/112758560
[20._Configuration]: https://blog.csdn.net/ming19951224/article/details/112759717
[21._springboot_jar]: https://dominick-li.blog.csdn.net/article/details/119024251
[22._RocketMQ]: https://dominick-li.blog.csdn.net/article/details/119523197