Swagger

1. 什么是swagger？

   swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法，参数和模型紧密集成到服务器。

2. swagger的使用

   • 导入依赖

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

3. 配置swagger

   • 创建config层编写Swagger配置

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

   • Swagger3.0的测试地址：http://localhost:8080/swagger-ui/index.html

4. 配置Swagger: Swagger的bean实例Docket

   • 创建配置类配置Swagger

   package com.test.swagger.config;
   
           import org.springframework.context.annotation.Bean;
           import org.springframework.context.annotation.Configuration;
           import springfox.documentation.oas.annotations.EnableOpenApi;
           import springfox.documentation.spi.DocumentationType;
           import springfox.documentation.spring.web.plugins.Docket;
   
   @Configuration
   @EnableOpenApi //开启Swagger3.0
   public class SwaggerConfig {
   
       //配置swagger的Docket的bean实例
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.OAS_30);
       }
   }
   

   • 配置Swagger信息ApiInfo

    //配置Swagger信息apiInfo
       private ApiInfo apiInfo() {
           //作者信息
           Contact contact= new Contact(
                   "author",
                   "https://i.cnblogs.com/posts/edit;postId=18199833",
                   "1151148068@qq.com");//作者信息
           return new ApiInfo(
                   "大标题",
                   "描述",
                   "版本号",
                   "组织",
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList<>());
       }
   

   • 设置扫描包及过滤完善上面的Docket

     //配置swagger的Docket的bean实例
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.OAS_30)
                   .apiInfo(apiInfo())//自己定义的apiInfo（）
                   .select()
                   //RequestHandlerSelectors配置要扫描接口的方式
                   //basePackage指定要扫描的包
                   .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
                   //paths()过滤什么路径
                   .paths(PathSelectors.ant("/new/**"))
                   .build();
       }
   

   • 设置Swagger启动与关闭：在.apiInfo(apiInfo())后面进行添加.enable(false)
   • 如何在对应的项目环境下控制是否开启：开发环境开启Swagger，生产环境就要关闭Swagger
     • 编写不同环境下的配置文件
     • 编写配置类获取项目环境

       //配置swagger的Docket的bean实例
       @Bean
       public Docket docket(Environment environment){
   
           //设置要显示的swagger的环境
           Profiles profiles =Profiles.of("dev");
           //通过environment.acceptsProfiles判断是否处在自己设定的环境中
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.OAS_30)
                   .apiInfo(apiInfo())
                   .enable(flag)
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
                   .build();
       }
   

   • 设置分组：.groupName("A")，多个分组就是多人协作开发时每个人分组，就是多个Docket实例

   • 接口注释及实体类注释

     @Api(tags = "Controller层")：放在类上，描述类的作用
     @ApiOperation(value = "hello方法",notes = "方法描述")：放在方法上，描述具体的方法
     @ApiParam("用户名")：参数描述