Swagger的使用

官网： Swagger官网

集成Swagger

1. 导入坐标

<!--        swagger-->
        <dependency>
		  <groupId>io.springfox</groupId>
		  <artifactId>springfox-boot-starter</artifactId>
  		  <version>3.0.0</version>
		</dependency>

2. 配置 Swagger（配置类），添加 @EnableOpenApi 注解

@Configuration
@EnableOpenApi
public class MySwaggerConfig {
}

3. 访问路径：http://localhost:8080/swagger-ui/index.html

配置Swagger

1. 配置类中配置 Docket

    @Bean
    public Docket docket() {

        Docket docket = new Docket(DocumentationType.OAS_30).apiInfo(
                new ApiInfo("张三的Swagger 文档",
                        "文档描述",
                        "3.0",
                        "https://www.baidu.com",
                        //作者信息
                        new Contact("张三", "http://localhost:8080/hello", "2685341645@qq.com"),
                        "Apache 3.0",
                        "http://www.apache.org/licenses/LICENSE-3.0",
                        new ArrayList())
        );
        return docket;
    }

2. 配置扫描接口
   Docket.select()

@Bean
    public Docket docket() {

        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(true) //关闭则不能访问 Swagger
                .select()
//                RequestHandlerSelectors：配置要扫描接口的方式
//                    basePackage：指定扫描包
//                    any()：扫描全部
//                    none()：不扫描
//                    withMethodAnnotation()：扫描带有该注解的方法
//                    withClassAnnotation()：扫描带有该注解的类

                .apis(RequestHandlerSelectors.basePackage("com.hbsi.controller"))
//              扫描路径
                .paths(PathSelectors.ant("/**"))
                .build();
        return docket;
    }
    private ApiInfo apiInfo(){
        ApiInfo apiInfo = new ApiInfo("张三的Swagger 文档",
                "文档描述",
                "3.0",
                "https://www.baidu.com",
                //作者信息
                new Contact("张三", "http://localhost:8080/hello", "2685341645@qq.com"),
                "Apache 3.0",
                "http://www.apache.org/licenses/LICENSE-3.0",
                new ArrayList());

        return apiInfo;
    }

3. 只在生产环境下使用 swagger，发布时不使用

   • 判断是不是生产环境 flag = false
     • 获取激活的环境：方法参数注入 Environment

     //import org.springframework.core.env.Environment;
     //获取项目的环境：
     boolean flag = environment.acceptsProfiles(Profiles.of("dev"));
     

   • 注入 enable(flag)

4. 配置多个分组：docket 设置分组名即可

 @Bean
    public Docket docket1(){
        Docket docket = new Docket(DocumentationType.OAS_30);
        docket.groupName("a");
        return docket;
    }
    @Bean
    public Docket docket2(){
        Docket docket = new Docket(DocumentationType.OAS_30);
        docket.groupName("b");
        return docket;
    }

5. 实体类配置

   @ApiModel("用户实体类")
   public class User {
   
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
   }
   
   //下面为 controller
   
   //只要我们的接口中，返回值存在实体类，就会被扫描到 Swagger 中
       @ApiOperation("返回参数的控制器")
       @GetMapping("/world")
       public String world(@ApiParam("要返回的字符串") String word){
           return word;
       }
   

   
6. 自带测试功能：
   

常用注解

1. controller

   类上 @Api(tags = “讲师管理”)
   方法上 @ApiOperation(“查询所有讲师”)
   参数上 @ApiParam(“讲师id”)

2. 实体类

   @Data
   @EqualsAndHashCode(callSuper = false)
   @Accessors(chain = true)
   @ApiModel(value="EduTeacher对象", description="讲师")
   public class EduTeacher implements Serializable {
   
       private static final long serialVersionUID = 1L;
   
       @ApiModelProperty(value = "讲师姓名")
       private String name;
   
       @ApiModelProperty(value = "讲师简介")
       private String intro;
   
       @ApiModelProperty(value = "逻辑删除 1（true）已删除， 0（false）未删除")
       private Boolean isDeleted;
   
   
   
   }