Java中自定义扩展Swagger的能力，自动通过枚举类生成参数取值含义描述的实现策略("Java实现自定义Swagger扩展：自动生成枚举类参数取值含义描述的策略")

原创

ithorizon 7个月前 (10-21) 阅读数 35 #后端开发

Java实现自定义Swagger扩展：自动生成枚举类参数取值含义描述的策略

一、引言

Swagger是一个流行的API文档生成工具，它可以帮助开发人员敏捷生成API文档，让API的使用和测试更加便捷。在Java项目中，我们通常会使用Swagger来生成API接口的文档。然而，有时候我们需要在API文档中添加对枚举类参数取值的详细描述，以便更好地说明每个枚举值的具体含义。本文将介绍一种策略，用于在Swagger中自动生成枚举类参数取值含义描述。

二、Swagger简介

Swagger是一个基于OpenAPI规范（以前称为Swagger规范）的工具集，用于设计、构建、测试和记录RESTful Web服务。Swagger的核心是一个YAML或JSON格式的规范文件，它定义了API的结构和功能。通过这个规范文件，Swagger可以生成可交互的API文档，并赞成自动生成客户端代码。

三、问题背景

在实际开发中，我们频繁会在API接口中使用枚举类型作为参数。然而，Swagger默认生成的文档中并不会显示枚举值的详细描述，这也许会让文档的可读性和易用性降低。为了解决这个问题，我们需要自定义Swagger的扩展，使其能够自动生成枚举类参数取值的含义描述。

四、实现策略

要实现这个功能，我们需要自定义一个Swagger的扩展，并在其中处理枚举类型。以下是一种也许的实现策略：

4.1 创建自定义枚举类注解

首先，我们需要创建一个自定义注解，用于标记枚举类，并存储枚举值的描述信息。


@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface EnumDescription {
    String[] descriptions();
}

4.2 创建枚举类并使用自定义注解

接下来，我们创建一个枚举类，并使用上面定义的注解来标记枚举值。


@EnumDescription({"正常", "异常", "未知"})
public enum Status {
    NORMAL("正常"),
    ERROR("异常"),
    UNKNOWN("未知");
    private final String description;
    Status(String description) {
        this.description = description;
    }
    public String getDescription() {
        return description;
    }
}

4.3 自定义Swagger扩展

现在我们需要自定义一个Swagger扩展，用于处理枚举类型并生成描述信息。我们可以通过继承Swagger的扫描器类来实现。


import springfox.documentation.builders.PropertySpecificationBuilder;
import springfox.documentation.schema.property.PropertySpecification;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelTransformer;
import springfox.documentation.spi.schema.contexts.ModelContext;
import springfox.documentation.swagger.common.SwaggerPluginSupport;
import java.lang.reflect.Type;
import java.util.Arrays;
import java.util.List;
public class EnumModelTransformer extends SwaggerPluginSupport implements ModelTransformer {
    @Override
    protected boolean supportsDocumentationType(DocumentationType delimiter) {
        return true;
    }
    @Override
    public List transformProperties(ModelContext context, PropertySpecification[] properties) {
        for (PropertySpecification property : properties) {
            Type type = property.getType();
            if (type instanceof ParameterizedType) {
                Type rawType = ((ParameterizedType) type).getRawType();
                if (rawType == Enum.class) {
                    EnumDescription enumDescription = property.getBeanProperty().get().getMethod().getDeclaringClass().getAnnotation(EnumDescription.class);
                    if (enumDescription != null) {
                        property.setDescription(Arrays.toString(enumDescription.descriptions()));
                    }
                }
            }
        }
        return Arrays.asList(properties);
    }
}

4.4 配置Swagger

最后，我们需要在Swagger的配置中添加我们自定义的扩展。


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build()
                .plugins(new Plugin[] {new EnumModelTransformer()});
    }
}