6 Swagger3 Docket 开关&过滤&分组配置详解结合SpringBoot2

Posted 2021-10-19 java1234_小锋

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了6 Swagger3 Docket 开关&过滤&分组配置详解结合SpringBoot2相关的知识，希望对你有一定的参考价值。

我们可以通过设置Docket，可以配置很多功能，比如是否开启swagger，过滤，分组等；

6.1 开关设置enable

一般情况，我们只有在开发环境才会用到swagger，正式环境需要关闭swagger，一个是安全问题，还有一个是用了swagger会影响系统运行速度；

我们通过设置Docket对象的enable即可；

/**
 * 配置swagger的Docket bean
 * @return
 */
@Bean
public Docket createRestApi() {
	return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
			.enable(false)   // 开关
			.apiInfo(createApiInfo());
}

设置后，重启项目，发现已经看不到API信息了；

6.2 设置过滤

有些情况，我们需要指定固定包路径下的类生成API，或者根据前端用户路径请求过滤；

使用过滤，必须先调用select方法；

通过apis方法，basePackage可以根据包路径来生成特定类的API，

any方法是默认所有都有效，none方法都无效；

withClassAnnotation根据类注解，withMethodAnnotation是根据方法注解；

一般我们用的是 basePackage方法；

具体实例：

/**
 * 配置swagger的Docket bean
 * @return
 */
@Bean
public Docket createRestApi() {
	return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
			.enable(true)   // 开关
			.select()
			.apis(RequestHandlerSelectors.basePackage("com.java1234.controller"))  // 指定扫描的包  常用方式
			.build()
			.apiInfo(createApiInfo());
}

最后要加 build()方法；

类似的还有一个根据请求路径的paths方法；

一般用ant匹配路径；

any是匹配任意路径，none是都不匹配，regex是正则匹配；

具体实例：

/**
 * 配置swagger的Docket bean
 * @return
 */
@Bean
public Docket createRestApi() {
	return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
			.enable(true)   // 开关
			.select()
			.paths(PathSelectors.ant("/java1234/**"))  // 匹配 /java1234/**请求路径
			.build()
			.apiInfo(createApiInfo());
}

swagger-ui视图只显示过滤后的API接口信息；

6.3 设置分组

在实际项目开发中，把复杂项目划分多模块给多个小组或者多个人负责开发，所以每个小组或者个人要实现自己的分组，方便查找到API接口开发负责人，沟通和处理问题；

我们通过groupName方法可以设置组名；

实例：

/**
 * 配置swagger的Docket bean
 * @return
 */
@Bean
public Docket createRestApi() {
	return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
			.groupName("开发组001")
			.enable(true)   // 开关
			.select()
			.build()
			.apiInfo(createApiInfo());
}

刷新界面：

发现组名变了；

现在话，我们结合前面学过的过滤，通过apis的basePackage方法，搞两个组，分别扫描不同的包路径；

模拟分组开发，controller包下建两个子包，分别是one和two包，用来模拟两个业务模块；

简单搞个HelloWorldController2

package com.java1234.controller.two;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author java1234_小锋
 * @site www.java1234.com
 * @company 南通小锋网络科技有限公司
 * @create 2021-09-22 15:46
 */
@Api(tags="helloWorld2类测试")
@RestController
public class HelloWorldController2 {

    /**
     * helloWorld测试
     * @return
     */
    @ApiOperation("测试方法2")
    @GetMapping("/helloWorld2")
    public String helloWorld(){
        return "helloWorld2";
    }
    
}

我们搞两个Docket和两个ApiInfo

package com.java1234.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 java.util.ArrayList;

/**
 * @author java1234_小锋
 * @site www.java1234.com
 * @company 南通小锋网络科技有限公司
 * @create 2021-09-21 10:42
 */
@Configuration
public class Swagger3Config {

    /**
     * 配置swagger的Docket bean
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组001")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.java1234.controller.one"))  // 指定扫描的包  常用方式
                .build()
                .apiInfo(createApiInfo());
    }

    /**
     * 配置swagger的Docket bean
     * @return
     */
    @Bean
    public Docket createRestApi2() {
        return new Docket(DocumentationType.OAS_30)  // 指定swagger3.0版本
                .groupName("开发组002")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.java1234.controller.two"))  // 指定扫描的包  常用方式
                .build()
                .apiInfo(createApiInfo2());
    }

    /**
     * 配置swagger的ApiInfo bean
     * @return
     */
    @Bean
    public ApiInfo createApiInfo(){
        return new ApiInfo("Java1234 Swagger"
               ,"Java1234 Api Documentation"
                ,"3.0"
                ,"http://www.java1234.vip"
                ,new Contact("小锋", "http://www.java1234.vip", "caofeng2012@126.com")
                ,"Apache 2.0"
                ,"http://www.apache.org/licenses/LICENSE-2.0"
                ,new ArrayList());
    }

    /**
     * 配置swagger的ApiInfo bean
     * @return
     */
    @Bean
    public ApiInfo createApiInfo2(){
        return new ApiInfo("Java1234 Swagger"
                ,"Java1234 Api Documentation"
                ,"3.0"
                ,"http://www.java1234.vip"
                ,new Contact("小丽", "http://www.java1234.vip", "caofeng2012@126.com")
                ,"Apache 2.0"
                ,"http://www.apache.org/licenses/LICENSE-2.0"
                ,new ArrayList());
    }


}