526互联

springboot 引入swagger3.0 knife4j API

发布时间 2023-09-02 11:03:47作者: Tk小武

1.引入依赖pom

<properties>
    <swagger-version>3.0.0</swagger-version>
    <swagger-knife4j>3.0.3</swagger-knife4j>
</properties>

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-dependencies</artifactId>
    <version>2.3.12.RELEASE</version>
</parent>
<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger-version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger-version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${swagger-version}</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${swagger-knife4j}</version>
</dependency>

2.构建swagger配置类
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.*;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean enable;

    @Bean(value = "defaultApi2")
    public Docket createRestApi() {
        String groupName="接口平台";

        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(creatApiInfo())
                .groupName(groupName) //设置API文档的分组名称。
                .enable(enable)  //是否开启swagger
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) //扫描包含 @RestController 注解的方法。
                .paths(PathSelectors.any())  //暴露所有接口路径。
                .build()
                .protocols(protocols("http","https")) // 支持的通讯协议集合
                .securitySchemes(securitySchemes()) //添加请求头和请求参数
                .securityContexts(securityContexts()); //授权信息全局应用;
        return docket;
    }

    /**
     * 认证的安全上下文
     * @return
     */
    public List<SecurityScheme> securitySchemes(){
        ArrayList<SecurityScheme> list = new ArrayList<>();
        //请求的参数 Authorization:
        list.add(new ApiKey("Authorization","Authorization","header"));
        // apiKeyList.add(new ApiKey("x-access-token", "x-access-token", "header"));
        return list;
    }

    public List<SecurityContext> securityContexts(){
        ArrayList<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(securityReferences())
                .forPaths(PathSelectors.any()).build());
        return securityContexts;
    }

    public List<SecurityReference> securityReferences(){
        //全局作用域
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        ArrayList<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization",authorizationScopes));
        return securityReferences;
    }

    /**
     * 支持的通讯协议集合
     * @param type 类型值
     * @return
     */
    public Set<String> protocols(String... type){
        HashSet<String> set = new HashSet<>();
        for (String s : type) {
            set.add(s);
        }
        return set;
    }
    /**
     * 构建首页摘要
     * @return
     */
    public ApiInfo creatApiInfo(){
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("SpringBoot - knife4j API ")   //标题
                .description("Swagger 3.0 测试API ")       //描述
                .termsOfServiceUrl("http://127.0.0.1")  //服务Url
                .contact(new Contact("xxxxxx", "http://xxxx.com.cn/", "wlw@xxxx.xxx")) //介绍
                .version("3.0") //版本
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
        return apiInfo;
    }

}