swagger2场景+（自定义提示）spring-boot-configuration-processor的使用场景

冰缝大坑

已于 2024-04-02 13:48:42 修改

阅读量617

点赞数 12

文章标签： java spring spring boot

于 2024-02-18 21:46:27 首次发布

本文链接：https://blog.csdn.net/m0_62787705/article/details/136157119

版权

文章目录

一、配置swagger2
二、spring-boot-configuration-processor的使用场景

一、配置swagger2

1、pom.xml

<!-- swagger2模块 -->
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>

2、配置类

忽略@ConfigurationProperties注解，这个来自spring-boot-configuration-processor依赖与swagger2配置无关可省略
分离配置类所需要的属性作为属性类，这个属性类可复合使用

属性类

package com.wu.pan.framework.swagger2;

import com.wu.pan.framework.constants.RPanConstants;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * @Classname Swagger2ConfigProperties
 * @Description swagger2配置属性实体
 * @Date 2024-01-25 12:34
 * @Created by cc
 * 属性类
 */

@Data
@Component
@ConfigurationProperties(prefix = "swagger2")
public class Swagger2ConfigProperties {
    private boolean show = true;

    private String groupName = "rpan";

    private String basePackage = RPanConstants.BASE_COMPONENT_SCAN_PATH;

    private String title = "rpan-framework-server";

    private String description = "rpan-framework-server";

    private String termsOfServiceUrl = "http://127.0.0.1:${server.port}";

    private String contactName = "cc";

    private String contactUrl = "https://blog.csdn.net/m0_62787705?spm=1000.2115.3001.5343";

    private String contactEmail = "cc@wu.com";

    private String version = "1.0";
}

配置类

package com.wu.pan.framework.swagger2;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Classname Swagger2Config
 * @Description
 * @Date 2024-01-25 12:34
 * @Created by cc
 * 配置类
 */

@SpringBootConfiguration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Slf4j
public class Swagger2Config {

    @Autowired
    private Swagger2ConfigProperties properties;

    @Bean
    public Docket panServerApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .enable(properties.isShow())
                .groupName(properties.getGroupName())
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getBasePackage()))
                .paths(PathSelectors.any())
                .build();
        log.info(" swagger2 成功加载！！！！！");
        return docket;
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getTitle())
                .description(properties.getDescription())
                .termsOfServiceUrl(properties.getTermsOfServiceUrl())
                .contact(new Contact(properties.getContactName(), properties.getContactUrl(), properties.getContactName()))
                .version(properties.getVersion())
                .build();
    }
}

3、启动类添加@EnableSwagger2注解

@SpringBootApplication(scanBasePackages="com.ttbank")
@EnableSwagger2 //就是这个注解
public class FileApplication {
    public static void main(String[] args) {
        SpringApplication.run(FileApplication.class,args);
    }
}

4、配置application.yaml配置


swagger2:
  show: true
  group-name: ${spring.application.name}
  base-package: com.wu.pan
  title: rpan-server docs
  description: rpan-server docs
  terms-of-service-url: http://127.0.0.1:${server.port}
  contact-name: cc
  contact-url: https://blog.csdn.net/m0_62787705?spm=1000.2115.3001.5343
  contact-email: cc@wu.com
  version: 1.0

5、常用注解

具体使用看他人博客--------注解使用

@Api：用在请求的类上，表示对类的说明.
属性：
tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在请求的方法上，说明方法的用途、作用。
属性：
value=“说明方法的用途、作用”
notes=“方法的备注说明”

@ApiImplicitParams：用在请求的方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
属性：
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：

@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在属性上，描述响应类的属性

@ApiParam是一个描述方法参数的注解
　　注解内的常用属性有
　　name：参数名（与请求参数参数名一致）
　　value：参数说明
　　required：是否必须

ApiParam和@ApiImplicitParam类似，都是对方法参数进行标注，但是注解添加的位置不同，@ApiParam添加在方法参数前，@ApiImplicitParam添加在方法前，@ApiImplicitParam拥有dataType和paramType

6、访问 localhost：端口号/doc.html

在这里插入图片描述

二、spring-boot-configuration-processor的使用场景

1、依赖的作用

Spring Boot Configuration Processor（spring-boot-configuration-processor）是一个用于生成META-INF/spring-configuration-metadata.json文件的插件。这个文件包含了Spring Boot应用程序的配置元数据，可以帮助开发者在IDE中更好地理解和导航配置属性.

场景理解: swagger2分离出来的配置类,这个配置类的属性名需要在application.yaml文件使用.如果书写这些属性名时有提示就好了,所以将属性类生成为文件META-INF/spring-configuration-metadata.json文件,只要生成这个文件那么写application.yaml时就有提示了.

ps:文件如下,出现下面这个文件就表示成功了(文件在target中).
在这里插入图片描述

2、具体过程

比较好的自定义实现，来自其他人博客

依赖和插件（pom.xml文件）

编译器插件会根据配置类生成 spring-configuration-metadata.json。
Spring Boot 提供了一个名为 spring-boot-configuration-processor 的依赖，这个依赖实际上就是一个编译器插件。当在项目中引入这个依赖时，它会在编译阶段自动扫描配置类，并生成 META-INF/spring-configuration-metadata.json 文件。这个 JSON 文件包含了配置类的元数据信息，如配置属性的分组（groups）和提示信息（hints），这使得 IDE 能够提供智能提示和自动完成功能(自定义提示)，从而提升开发体验。
此外，如果需要对自动生成的元数据进行扩展或自定义，可以手动创建 additional-spring-configuration-metadata.json 文件在 resources/META-INF 目录下，以提供额外的配置信息。
总的来说，spring-boot-configuration-processor 插件在编译时会根据配置类生成 spring-configuration-metadata.json 文件，这是 Spring Boot 项目智能化开发的一个重要组成部分。
compiler-plugin确保正确编译

         <!--自定义属性提示：配置文件提示，（绑定一个属性类文件，提示属性，简化编写）自己编写的配置类可以有提示-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>8</source>
                    <target>8</target>
                    <encoding>utf-8</encoding>
                    <skip>true</skip>
                </configuration>
            </plugin>
        </plugins>
    </build>

绑定配置类

@ConfigurationProperties(prefix = “swagger2”)这个注解主要用于Spring Boot项目中，用于将配置文件中的属性值绑定到一个Java类上。这样可以方便地在代码中使用这些属性值。
绑定属性类的具体规则
绑定配置类后，配置类和配置文件（yml文件，会自动扫描所由yml中prefix开头的属性）的信息就是一体的了。配置类是默认值，如果配置文件定义后就使用配置文件中的值。

package com.wu.pan.framework.swagger2;

import com.wu.pan.framework.constants.RPanConstants;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * @Classname Swagger2ConfigProperties
 * @Description swagger2配置属性实体
 * @Date 2024-01-25 12:34
 * @Created by cc
 * 属性类
 */

@Data
@Component
@ConfigurationProperties(prefix = "swagger2")
public class Swagger2ConfigProperties {
    private boolean show = true;

    private String groupName = "rpan";

    private String basePackage = RPanConstants.BASE_COMPONENT_SCAN_PATH;

    private String title = "rpan-framework-server";

    private String description = "rpan-framework-server";

    private String termsOfServiceUrl = "http://127.0.0.1:${server.port}";

    private String contactName = "cc";

    private String contactUrl = "https://blog.csdn.net/m0_62787705?spm=1000.2115.3001.5343";

    private String contactEmail = "cc@wu.com";

    private String version = "1.0";
}

additional-spring-configuration-metadata.json文件创建

additional-spring-configuration-metadata.json 通常由用户手动创建，用于为特定的配置项提供额外的元数据信息，如在 IDE 中提供更好的代码提示和自动完成功能。
就是说additional-spring-configuration-metadata.json是对上面配置类的一个信息补充，比如说补充些注释之类，在书写yaml文件时除了提示属性时还有注释。
而 spring-configuration-metadata.json 文件则是由 Spring Boot 的自动配置机制生成的，它包含了所有自动配置相关的配置属性的元数据信息，使得 IDE 能够理解这些配置项及其类型，从而为用户提供智能提示和辅助。

创建additional-spring-configuration-metadata.json文件,
格式如下，根据配置类创建(additional-spring-configuration-metadata.json文件)

具体的文件创建规则

在这里插入图片描述

{
  "properties": [
 /*
       {
      
      "name": "prefix.属性名",
      "type": "属性类型"
      "description": "描述",
      "defaultValue": true
    },
*/

    {
      "name": "swagger2.show",
      "type": "java.lang.Boolean",
      "description": "是否展示接口文档",
      "defaultValue": true
    },
    {
      "name": "swagger2.group-name",
      "type": "java.lang.String",
      "description": "组名称",
      "defaultValue": "rpan"
    },
    {
      "name": "swagger2.title",
      "type": "java.lang.String",
      "description": "接口文档标题",
      "defaultValue": "rpan-framework-server"
    },
    {
      "name": "swagger2.description",
      "type": "java.lang.String",
      "description": "接口文档描述",
      "defaultValue": "rpan-framework-server"
    },
    {
      "name": "swagger2.terms-of-service-url",
      "type": "java.lang.String",
      "description": "接口文档基础请求路径",
      "defaultValue": "http://127.0.0.1:${server.port}"
    },
    {
      "name": "swagger2.base-package",
      "type": "java.lang.String",
      "description": "接口文档基础接口扫描路径",
      "defaultValue": "com.wu.pan"
    },
    {
      "name": "swagger2.contact-name",
      "type": "java.lang.String",
      "description": "联系人名称",
      "defaultValue": "cc"
    },
    {
      "name": "swagger2.contact-url",
      "type": "java.lang.String",
      "description": "联系人地址",
      "defaultValue": "https://blog.csdn.net/m0_62787705?spm=1000.2115.3001.5343"
    },
    {
      "name": "swagger2.contact-email",
      "type": "java.lang.String",
      "description": "联系人邮箱",
      "defaultValue": "cc@wu.com"
    },
    {
      "name": "swagger2.version",
      "type": "java.lang.String",
      "description": "项目版本",
      "defaultValue": "1.0"
    }
  ]
}

编译

在这里插入图片描述

在编译前必须先maven clean（之前编译的不一定正确）然后maven compile

使用疑难杂症–不生效

相关博文：
自定义提示1
自定义提示2

冰缝大坑

关注

12
点赞
踩
9

收藏

觉得还不错? 一键收藏
2
评论
swagger2场景+（自定义提示）spring-boot-configuration-processor的使用场景

ApiParam和@ApiImplicitParam类似，都是对方法参数进行标注，但是注解添加的位置不同，@ApiParam添加在方法参数前，@ApiImplicitParam添加在方法前，@ApiImplicitParam拥有dataType和paramType。这个文件包含了Spring Boot应用程序的配置元数据，可以帮助开发者在IDE中更好地理解和导航配置属性.ps:文件如下,出现下面这个文件就表示成功了(文件在target中).swagger2分离出来的配置类,这个配置类的属性名需要在。
复制链接

扫一扫