【Spring】yaml自定义参数添加提示功能

返回首页

1. 说明

编写SpringBoot项目时是不是羡慕spring以及第三方插件的自动提示功能。其实实现很简单，且听我道来。

2. 依赖

对于maven和gradle依赖写法不一样，为了避免依赖，均列在下面

// gradle中引入依赖 
dependencies {
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
 }
1
2
3
4

<dependency>
  <groupId>org.springframework.bootgroupId>
  <artifactId>spring-boot-configuration-processorartifactId>
  <optional>trueoptional>
dependency>
1
2
3
4
5
6

3. 处理流程（以自定义swagger配置为例）

3.1 定义自定义参数SwaggerProperties

注意：这里的提示是需要写的，这是后面yaml中自定义参数的提示内容

@Data
@ConfigurationProperties(prefix = "seed.swagger")
public class SwaggerProperties {
    /**
     * 是否启用，默认：启用
     */
    private boolean enable = true;
    /**
     * 名称,默认：seed接口管理
     */
    private String title = "Seed接口管理";
    /**
     * 简介
     */
    private String description;
    /**
     * 作者，默认：叶甯
     */
    private String author = "叶甯";
    /**
     * 版本，默认：1.0.0
     */
    private String version = "1.0.0";
    /**
     * 全局鉴权参数，默认：Authorization
     */
    private String security = "Authorization";

    /**
     * 定义分组
     */
    private List<GroupConfig> groupConfig = new ArrayList<>();

    /**
     * 分组配置
     */
    @Data
    @NoArgsConstructor
    public static class GroupConfig {
        /**
         * 分组名称
         */
        private String group;
        /**
         * 扫描包地址
         */
        private List<String> packagesToScan = new ArrayList<>();

    }
}
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

3.2 通过Configuration启用并使用自定义参数

@AutoConfiguration
@Slf4j
@EnableConfigurationProperties(SwaggerProperties.class) // 启用SwaggerProperties
public class SwaggerAutoConfiguration implements BeanFactoryAware {
    @Resource
    private SwaggerProperties swaggerProperties;
    private BeanFactory beanFactory;

    @Bean
    public OpenAPI openAPI() {
        log.info("swggger加载中... OpenAPI接口文档信息");
        OpenAPI openApi = new OpenAPI();
        //基础参数信息
        openApi.setInfo(getInfo());
        //指定安全模式参数
        securitySchemes(openApi);
        return openApi;
    }

    //这个是自定义分组和返回鉴权策略的he
    @Bean
    public GroupedOpenApi groupedOpenApi() {
        log.debug("swggger加载中... GroupedOpenApi 接口文档信息");
        ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory;
        final OperationCustomizer globalHeader = (operation, handlerMethod) -> {
            operation.addParametersItem(new HeaderParameter()
                    .$ref("#/components/parameters/testheader"));
            return operation;
        };
        if (swaggerProperties != null && !ObjectUtils.isEmpty(swaggerProperties.getGroupConfig())) {
            List<SwaggerProperties.GroupConfig> groupConfigs = swaggerProperties.getGroupConfig();
            for (SwaggerProperties.GroupConfig entity : groupConfigs) {
                GroupedOpenApi api = GroupedOpenApi.builder()
                        .group(entity.getGroup())
                        .packagesToScan(entity.getPackagesToScan().toArray(new String[entity.getPackagesToScan().size()]))
                        .addOperationCustomizer(globalHeader)
                        .addOpenApiCustomizer(getResponseMessages())
                        .build();
                //注册成bean
                configurableBeanFactory.registerSingleton(entity.getGroup(), api);
            }
        }
        return null;
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private void securitySchemes(OpenAPI openApi) {
        if (swaggerProperties != null && !ObjectUtils.isEmpty(swaggerProperties.getSecurity())) {
            SecurityScheme securityScheme = new SecurityScheme()
                    .name(swaggerProperties.getSecurity())
                    .scheme("bearer ")
                    .bearerFormat("JWT")
                    .type(SecurityScheme.Type.HTTP)
                    .in(SecurityScheme.In.HEADER)
                    .description("安全模式-指定参数：" + swaggerProperties.getSecurity());
            openApi.schemaRequirement(swaggerProperties.getSecurity(), securityScheme)
                    .addSecurityItem(new SecurityRequirement().addList(swaggerProperties.getSecurity()));
        }
    }

    private Info getInfo() {
        if (swaggerProperties == null) {
            swaggerProperties = new SwaggerProperties();
        }
        Contact contact = new Contact()
                .name(ObjectUtils.isEmpty(swaggerProperties.getAuthor()) ? "作者" : swaggerProperties.getAuthor());
        Info info = new Info()
                .title(ObjectUtils.isEmpty(swaggerProperties.getTitle()) ? "接口文档" : swaggerProperties.getTitle())
                .version(ObjectUtils.isEmpty(swaggerProperties.getVersion()) ? "版本信息" : swaggerProperties.getVersion())
                .description(ObjectUtils.isEmpty(swaggerProperties.getDescription()) ? "更多请咨询服务开发者。" : swaggerProperties.getDescription())
                .contact(contact);
        return info;
    }

    /**
     * 设置全局响应状态
     *
     * @return
     */
    private OpenApiCustomizer getResponseMessages() {
        return openApi -> {
            openApi.getPaths().values().forEach(pathItem ->
                    pathItem.readOperations().forEach(operation -> {
                        //鉴权指定参数 Security
                        if (swaggerProperties != null && !ObjectUtils.isEmpty(swaggerProperties.getSecurity())) {
                            List<SecurityRequirement> securityList = new ArrayList<>();
                            securityList.add(new SecurityRequirement().addList(swaggerProperties.getSecurity()));
                            operation.security(securityList);
                        }
                    }));
        };
    }

    @Override
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
        this.beanFactory = beanFactory;
    }
}

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

4. 使用

注意：为了方便IDE识别对应的META-INF/spring-configuration-metadata.json ，在使用前需要将代码重新构建下，便于IDE生成提示json。
然后就可以愉快的使用了。