SpringBoot2.4.0 集成 Swagger2+knife4j_knife4j-spring-boot-starter 2.0.4

1. 简介：

Springboot 版本：2.4.0
Swagger 版本：3.0.0
knife4j 版本：2.0.7

2. 配置步骤：

1. pom 配置：

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

        <!-- 防止进入swagger页面报类型转换错误，排除3.0.0中的引用，手动增加1.6.2版本 -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.6.2</version>
        </dependency>

        <!--knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.7</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

2.SwaggerConfig 配置

package com.dechnic.tfoms.config;

import com.dechnic.tfoms.vo.ResultCode;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
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.ArrayList;
import java.util.Arrays;
import java.util.List;

import static org.springframework.http.HttpMethod.*;

/**
 * Swagger2的接口配置
 */
@EnableSwagger2
@EnableKnife4j
@Configuration
public class SwaggerConfig {

    /**
     * 是否开启swagger
     */
    @Value("${swagger.enabled}")
    private boolean enabled;

    /**
     * 设置请求的统一前缀
     */
    @Value("${swagger.pathMapping}")
    private String pathMapping;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        List<Response> responseList = new ArrayList<>();
        Arrays.stream(ResultCode.values()).forEach(resultCode -> {
            responseList.add(new ResponseBuilder().code(resultCode.getCode().toString()).description(resultCode.getMsg()).build());
        });

        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                // 扫描所有
//                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                /* 设置安全模式，swagger可以设置访问token */
//                .securitySchemes(securitySchemes())
//                .securityContexts(securityContexts())
                .pathMapping(pathMapping)
                .globalResponses(GET, responseList)
                .globalResponses(POST, responseList)
                .globalResponses(PUT, responseList)
                .globalResponses(DELETE, responseList);
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：能耗接口文档")
                // 描述
                .description("描述：用于查询能耗")
                // 作者信息
                .contact(new Contact("", null, null))
                // 版本
                .version("版本号: ")
                .build();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

3. ResultCode 通用返回代码

package com.dechnic.tfoms.vo;

import lombok.*;

/**
 * @className: ResultCode
 * @author: houqd
 * @date: 2022/11/1
 **/
@Getter
@AllArgsConstructor
@NoArgsConstructor
public enum ResultCode {
    SUCCESS(1,"成功"),
    ERROR(0,"失败"),
    SERVER_ERROR(500,"服务器错误"),
    UNLAWFUL(401,"无权限"),
    PARAM_ERROR(405,"参数错误"),
    NOT_LOGIN(406,"未登录");
    private Integer code;
    private String msg;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

4. OmsdcApiController 配置

package com.dechnic.tfoms.controller;/**
 * @className: OmsdcApiController
 * @author: houqd
 * @date: 2022/10/31
 **/

import com.dechnic.tfoms.mapper.VSMeterinstdatasMapper;
import com.dechnic.tfoms.service.IApiService;
import com.dechnic.tfoms.vo.*;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 *@description: 第三方能耗接口
 *@author:houqd
 *@time: 2022/10/31 18:11
 *
 */
@Api("能耗接口")
@RequestMapping("/omsdc")
@RestController
public class OmsdcApiController {
    @Autowired
    private IApiService apiService;

    @ApiOperation("获取表实时数据接口")
    @PostMapping(value = "/getMeterInstDatas",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
    public JsonVo getMeterInstDatas( @RequestBody(required = false) MeterInstDatasVo meterInstDatasVo){
        List<MeterInstDatasResult> meterInstDatasResults = apiService.searchMeterInstDatas(meterInstDatasVo);
        return JsonVo.success(meterInstDatasResults);
    }

    @ApiOperation("支路日数据接口")
    @PostMapping(value = "/searchServiceDayResult",consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
    public JsonVo searchServiceDayResult(@RequestBody(required = false) ServiceDayResultVo serviceDayResultVo){
        List<ServiceDayResultResult> serviceDayResultResults = apiService.searchServiceDayResult(serviceDayResultVo);
        return JsonVo.success(serviceDayResultResults);
    }

    @ApiOperation("支路月数据接口")
    @PostMapping(value = "/searchServiceMonthResult", consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
    public JsonVo searchServiceMonthResult(@RequestBody(required = false) ServiceMonthResultVo serviceMonthResultVo){
        List<ServiceMonthResultResult> serviceMonthResultResults = apiService.searchServiceMonthResult(serviceMonthResultVo);
        return JsonVo.success(serviceMonthResultResults);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

4. yml 配置

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
  pathMapping: /
1
2
3
4
5
6

5. 展示界面：