Swagger (二) --------- 配置 Swagger

心已赠人 2024-04-03 08:28 84阅读 0赞

#### 目录 ####

*  一、配置 Swagger
 *  二、配置扫描接口
 *  三、配置 Swagger 开关
 *  四、配置 API 分组
 *  五、实体配置

--------------------

## 一、配置 Swagger ##

**A、Swagger实例 Bean 是 Docket，所以通过配置 Docket 实例来配置 Swaggger**

@Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        
       return new Docket(DocumentationType.SWAGGER_2);
    }

**B、可以通过apiInfo()属性配置文档信息**

//配置文档信息
    private ApiInfo apiInfo() {
        
       Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
       return new ApiInfo(
               "Swagger学习", // 标题
               "学习演示如何配置Swagger", // 描述
               "v1.0", // 版本
               "http://terms.service.url/组织链接", // 组织链接
               contact, // 联系人信息
               "Apach 2.0 许可", // 许可
               "许可链接", // 许可连接
               new ArrayList<>()// 扩展
      );
    }

**C、Docket 实例关联上 apiInfo()**

@Bean
    public Docket docket() {
        
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

![在这里插入图片描述][e69344adf41e4cc0a507523b68625ab9.png]

## 二、配置扫描接口 ##

**A、构建 Docket 时通过 select() 方法配置怎么扫描接口**

@Bean
    public Docket docket() {
        
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.fancy.swaggerdemo.controller"))
          .build();
    }

**B、重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类**

![在这里插入图片描述][a7081ffd3d69466db8af5b3125d0c316.png]

**C、除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：**

any() // 扫描所有，项目中的所有接口都会被扫描到
    none() // 不扫描接口
    // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)
    basePackage(final String basePackage) // 根据包路径扫描接口

**D、除此之外，我们还可以配置接口扫描过滤：**

@Bean
    public Docket docket() {
        
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }

**E、这里的可选值还有**

any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制

![在这里插入图片描述][993ef29146524f83adadf6c8093f36d0.png]

## 三、配置 Swagger 开关 ##

**A、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了**

@Bean
    public Docket docket() {
        
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
          .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }

**B、如何动态配置当项目处于 test、dev 环境时显示 swagger，处于 prod 时不显示？**

@Bean
    public Docket docket(Environment environment) {
        
       // 设置要显示swagger的环境
       Profiles of = Profiles.of("dev", "test");
       // 判断当前是否处于该环境
       // 通过 enable() 接收此参数判断是否要显示
       boolean b = environment.acceptsProfiles(of);
       
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
          .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }

**C、可以在项目中增加一个dev的配置文件查看效果**

> spring boot允许你通过命名约定按照一定的格式(application-\{profile\}.properties)来定义多个配置文件，然后通过在application.properyies通过spring.profiles.active来具体激活一个或者多个配置文件，如果没有没有指定任何profile的配置文件的话，spring boot默认会启动application-default.properties。

![在这里插入图片描述][7490928d798e413b97041aaf5ecdf964.png]

## 四、配置 API 分组 ##

![在这里插入图片描述][976652be7a304c548dc99ceb3b0fe4f5.png]

**A、如果没有配置分组，默认是default。通过groupName()方法即可配置分组**

@Bean
    public Docket docket(Environment environment) {
        
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
          .groupName("hello") // 配置分组
           // 省略配置....
    }

**B、重启项目查看分组**

**C、如何配置多个分组？配置多个分组只需要配置多个docket即可：**

@Bean
    public Docket docket1(){
        
       return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        
       return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        
       return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

**D、重启项目查看即可**

## 五、实体配置 ##

**A、新建一个实体类**

@ApiModel("用户实体")
    public class User {
        
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
    }

**B、只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：**

@RequestMapping("/getUser")
    public User getUser(){
        
       return new User();
    }

**C、重启查看测试**

![在这里插入图片描述][065ad8c6e2f6460185b069f0bbba5134.png]  
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释
    @ApiModelProperty为类属性添加注释

[e69344adf41e4cc0a507523b68625ab9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/b157ee54433a43bcaaee13ed0968b701.png
[a7081ffd3d69466db8af5b3125d0c316.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/c3c25195055b41ed881b32ec9db053fd.png
[993ef29146524f83adadf6c8093f36d0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/ba7598523fc4443497a9b74775d84491.png
[7490928d798e413b97041aaf5ecdf964.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/d879e7fca2a94b1b8f6d23b017920082.png
[976652be7a304c548dc99ceb3b0fe4f5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/cefd76ac207e434db32530963f283994.png
[065ad8c6e2f6460185b069f0bbba5134.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/03/ee3b3c38fb2e4404a4aeb02bfa1c2faf.png