springboot使用Swagger笔记

Swagger简介

前后端分离：Vue + Springboot

后端时代：前端只用管理静态页面： html => 后端。

前后端分离时代：

• 后端：后端控制层、服务层、数据访问层（后端团队）
• 前端：前端控制层、视图层（前端团队）
  • 伪造后端数据，json，已经存在了，不需要后端，前端工程依旧可以跑起来。
• 前后端交互：通过接口API
• 前后端i昂对独立，松耦合
• 前后端甚至可以部署在不同的服务器上

产生问题：

• 前后端集成联调，前后端人员无法做到即时协商。最终导致问题集中爆发。

解决方案

• 首先指定schemal计划提纲，实时更新最新的API，降低集成风险。如：OpenProject、Git ...
• 前后端分离

  • 前端测试后端接口：postman

  • 后端提供几口，需要适时更新的消息及改动！

Swagger

• 号称世界上最流行的API框架
• RestFul Api文档在线自动生成工具 => Api文档与API定义同步更新
• 直接运行，可以在线测试API接口（支持多种语言：Java、Php ...）

在线项目使用Swagger需要springfox

• swagger2
• swagger-ui

springboot集成swagger

1. 新建一个springboot-web项目
2. 导入依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   

    

3. 编写测试工程
4. 简单配置swagger

   package com.ccb.fate.config;
   
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   }

   基本配置完成后启动项目，成功后访问 http://localhost:9000/swagger-ui.html#/

   配置Swaggert 

   Swagger的bean实例：Docket

   基本信息配置

   package com.ccb.fate.config;
   
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.core.env.Environment;
   import org.springframework.core.env.Profiles;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   import java.util.ArrayList;
   
   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
       // 配置Swagger2的Docket的Bean实例
       @Bean
       public Docket getDocket(Environment environment){
   
           /**
            * 因为环境不同，项目需要也有可能不同，根据环境，动态的设置Swagger是否生效
            * 比如开发环境我们需要用到Swagger进行测试，但是当项目上线后我们就不需要再使用Swagger，可以根据监控配置的环境进行动态设置
            */
           Profiles profiles = Profiles.of("dev");
           boolean b = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(getApiInfo())
                   // 是否启用Swagger，默认是true
                   //.enable(b)
                   .select()
                   // RequestHandlerSelectors：配置要扫描接口的方式，常用basePackage
                   // 还有几个其它形式的，不常用，可以进源码查看
                   .apis(RequestHandlerSelectors.basePackage("com.ccb.fate"))
                   // 过滤器，对扫描的接口进行过滤
                   //.paths(PathSelectors.ant(""))
                   .build();
       }
   
       // 配置Swagger信息，意义不大，直接进去看源码大家都懂，就是一展示的东西
       private ApiInfo getApiInfo(){
           return new ApiInfo(
                   "测试Swagger文档",
                   "Api Documentation",// 描述
                   "1.0",
                   "urn:tos",
                   new Contact("CP","",""),
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
   
       }
   }
   

    

   注解：

   @ApiModel：给实体添加注释

   @ApiModelProperty：给字段添加注释

   @Data
   @ApiModel("消息传输实体类")
   public class CompanyTransDto implements Serializable {
   
       private static final long serialVersionUID = 1L;
       @ApiModelProperty("消息ID")
       private Long id;
   
       /**
        * 企业名称
        */
       @ApiModelProperty("企业名称")
       private String name;
   
       /**
        * 企业头像
        */
       @ApiModelProperty("企业头像")
       private String picture;
   }

   @Api：给模块加注释

   @ApiOperation：给接口加注释

   @RequestMapping(value = "/user-center")
   @Api(tags = "用户中心")
   public class UserCenterController {
   
       @Resource
       private UserCenterService userCenterService;
   
       @DeleteMapping(value = "/client-management/{clientId}/delete")
       @ApiOperation("根据Id删除客户端地址接口")
       public ApiResponse DeleteUserClientById(@PathVariable(name = "clientId")Long id){
           log.info("USER-CENTER{} begin delete user-client by id",id);
           userCenterService.DeleteUserClientById(id);
           log.info("USER-CENTER{} end delete user-client by id",id);
           return ApiResponse.ofSuccess(null);
       }
   
       @GetMapping(value = "/client-management/list")
       @ApiOperation("查询客户端地址列表")
       public ApiResponse findUserClientList(){
           UserVO userVO = UserContext.getUserVO();
           Map<String, Object> result = userCenterService.getIPClientList(userVO.getCompanyId());
           return ApiResponse.ofSuccess(result);
       }
   }