栏目分类:
子分类:
返回
名师互学网用户登录
快速导航关闭
当前搜索
当前分类
子分类
实用工具
热门搜索
名师互学网 > IT > 软件开发 > 后端开发 > Java

swagger3 展示枚举类型

Java 更新时间: 发布时间: IT归档 最新发布 模块sitemap 名妆网 法律咨询 聚返吧 英语巴士网 伯小乐 网商动力

swagger3 展示枚举类型

原文是基于swagger2编写的,在原文的基础上做了相应的改造。适用于swagger3

原文:swagger展示枚举类型
https://blog.csdn.net/weixin_50276625/article/details/115858744

改造点:

1、将 @SwaggerDisplayEnum 注解改为 SwaggerDisplayEnum 接口,优点是会强制枚举类实现 description() 描述方法。
2、针对swagger3,实现类做了相应的调整

一、pom.xml的jar依赖


    io.springfox
    springfox-boot-starter
    3.0.0
    provided

二、SwaggerDisplayEnum 接口
public interface SwaggerDisplayEnum {
    String description();
}
三、枚举类实例
import lombok.AllArgsConstructor;
import lombok.Getter;


@Getter
@AllArgsConstructor
public enum DictFileFromType implements SwaggerDisplayEnum {

    
    FILE_STORAGE(1, "文件存储服务读取[默认]"),

    
    PARAM_BASE64(2, "参数Base64传递");

    private Integer value;
    private String info;

    @Override
    public String description() {
        return value + "-" + info;
    }
}
四、需要显示枚举类型的字段属性
通过 @ApiModelProperty 的 notes 属性标识枚举类的全路径

@ApiModelProperty(value = "word文件来源类型(可选参数).", notes = "***.dict.DictFileFromType")
private Integer docFileFromType = DictFileFromType.FILE_STORAGE.getValue();
五、swaggerConfig 配置文件

@ConditionalOnProperty(name = “spring.profiles.active”, havingValue = “dev”, matchIfMissing = true),仅当开发环境的时候才加载,生产环境则不会加载swagger。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.PropertySpecificationBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.Annotations;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;

@Slf4j
@Configuration
@EnableOpenApi
@ConditionalOnProperty(name = "spring.profiles.active", havingValue = "dev", matchIfMissing = true)
public class Swagger3Config implements ModelPropertyBuilderPlugin {

    
    @Bean
    public Docket createApi() {
        log.info("====> [Swagger3]开启.");
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档转换服务")
                .description("《文档转换服务》接口定义和规范")
                .termsOfServiceUrl("http://www.huaxinsign.com/")
                .contact(new Contact("华信云盛", "http://www.huaxinsign.com/", "unisign@huaxinsign.com"))
                .version("1.0")
                .license("版权所有©北京华信云盛科技有限公司")
                .build();
    }

    @Override
    public void apply(ModelPropertyContext context) {
        //为枚举字段设置注释
        descForEnumFields(context);
    }

    
    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }

    
    private void descForEnumFields(ModelPropertyContext context) {
        Optional annotation = Optional.empty();

        // 找到 @ApiModelProperty 注解修饰的枚举类
        if (context.getBeanPropertyDefinition().isPresent()) {
            annotation = Annotations.findPropertyAnnotation(context.getBeanPropertyDefinition().get(), ApiModelProperty.class);
        }

        //没有@ApiModelProperty 或者 notes 属性没有值,直接返回
        if (!annotation.isPresent() || StringUtils.isEmpty((annotation.get()).notes())) {
            return;
        }

        //@ApiModelProperties中的notes指定的class类型
        Class rawPrimaryType;
        try {
            rawPrimaryType = Class.forName((annotation.get()).notes());
        } catch (ClassNotFoundException e) {
            //如果指定的类型无法转化,直接忽略
            return;
        }

        Object[] subItemRecords = null;
        // 判断 rawPrimaryType 是否为枚举,且实现了 SwaggerDisplayEnum 接口
        if (Enum.class.isAssignableFrom(rawPrimaryType) && SwaggerDisplayEnum.class.isAssignableFrom(rawPrimaryType)) {
            // 拿到枚举的所有的值
            subItemRecords = rawPrimaryType.getEnumConstants();
        } else {
            return;
        }

        final List displayValues = Arrays.stream(subItemRecords).filter(Objects::nonNull)
                        // 调用枚举类的 description 方法
                        .map(p -> ((SwaggerDisplayEnum) p).description()).filter(Objects::nonNull).collect(Collectors.toList());

        String joinText = " (" + String.join("; ", displayValues) + ")";
        try {
            // 拿到字段上原先的描述
            Field mField = PropertySpecificationBuilder.class.getDeclaredField("description");
            mField.setAccessible(true);
            // context 中的 builder 对象保存了字段的信息
            joinText = mField.get(context.getSpecificationBuilder()) + joinText;
        } catch (Exception e) {
            log.error(e.getMessage());
        }

        // 设置新的字段说明并且设置字段类型
        context.getSpecificationBuilder().description(joinText);
    }

}
六、SpringMVC拦截器配置
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    }
}
七、SpringBoot启动类添加文档连接
public static void main(String[] args) {
    ConfigurableApplicationContext context = SpringApplication.run(DocConvertApplication.class, args);

    if(context.containsBean("swagger3Config")){
        try {
            // 访问地址http://host:port/productName/swagger-ui/
            log.info("====> [Swagger3]文档的访问路径:http://{}:{}/{}/swagger-ui/",
                    InetAddress.getLocalHost().getHostAddress(),
                    context.getEnvironment().getProperty("server.port"),
                    context.getEnvironment().getProperty("spring.application.name"));
        } catch (Exception ignored){}
    }
}
转载请注明:文章转载自 www.mshxw.com
本文地址:https://www.mshxw.com/it/975406.html
我们一直用心在做
关于我们 文章归档 网站地图 联系我们

版权所有 (c)2021-2022 MSHXW.COM

ICP备案号:晋ICP备2021003244-6号