Swagger的使用

1
package com.zcloud.web.core.config;
2

3
import java.util.ArrayList;
4
import java.util.List;
5
import org.springframework.beans.factory.annotation.Value;
6
import org.springframework.context.annotation.Bean;
7
import org.springframework.context.annotation.Configuration;
8
import io.swagger.annotations.ApiOperation;
9
import io.swagger.models.auth.In;
10
import springfox.documentation.builders.ApiInfoBuilder;
11
import springfox.documentation.builders.PathSelectors;
12
import springfox.documentation.builders.RequestHandlerSelectors;
13
import springfox.documentation.service.ApiInfo;
14
import springfox.documentation.service.ApiKey;
15
import springfox.documentation.service.AuthorizationScope;
16
import springfox.documentation.service.Contact;
17
import springfox.documentation.service.SecurityReference;
18
import springfox.documentation.spi.DocumentationType;
19
import springfox.documentation.spi.service.contexts.SecurityContext;
20
import springfox.documentation.spring.web.plugins.Docket;
21

22
/**
23
 * Swagger3的接口配置
24
 * 虽然使用Swagger 2的注解（@ApiOperation等），但生成的是Swagger 3（OpenAPI 3.0）文档
25
 */
26
@Configuration
27
public class SwaggerConfig {
28

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

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

37
    /**
38
     * 创建API
39
     */
40
    @Bean
41
    public Docket createRestApi() {
42
        return new Docket(DocumentationType.OAS_30)  // ← OAS_30表示Swagger 3
43
                .enable(enabled)
44
                .apiInfo(apiInfo())
45
                .select()
46
                // 扫描所有有@ApiOperation注解的方法（Swagger 2注解风格）
47
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
48
                .paths(PathSelectors.any())
49
                .build()
50
                /* 设置安全模式，支持token认证 */
51
                .securitySchemes(securitySchemes())
52
                .securityContexts(securityContexts())
53
                .pathMapping(pathMapping);
54
    }
55

56
    /**
57
     * 安全模式，token通过Authorization请求头传递
58
     */
59
    private List<SecurityScheme> securitySchemes() {
60
        List<SecurityScheme> apiKeyList = new ArrayList<>();
61
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
62
        return apiKeyList;
63
    }
64

65
    /**
66
     * 安全上下文
67
     */
68
    private List<SecurityContext> securityContexts() {
69
        List<SecurityContext> securityContexts = new ArrayList<>();
70
        securityContexts.add(
71
                SecurityContext.builder()
72
                        .securityReferences(defaultAuth())
73
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
74
                        .build());
75
        return securityContexts;
76
    }
77

78
    /**
79
     * 默认的安全上引用
80
     */
81
    private List<SecurityReference> defaultAuth() {
82
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
83
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
84
        authorizationScopes[0] = authorizationScope;
85
        List<SecurityReference> securityReferences = new ArrayList<>();
86
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
87
        return securityReferences;
88
    }
89

90
    /**
91
     * 添加摘要信息
92
     */
93
    private ApiInfo apiInfo() {
94
        return new ApiInfoBuilder()
95
                .title("若依管理系统_接口文档")
96
                .description("用于管理集团旗下公司的人员信息")
97
                .contact(new Contact("若依", null, null))
98
                .version("版本号:3.9.1")
99
                .build();
100
    }
101
}