Java 复杂enum显示在swagger-ui 以及line break列值解决方案

最新推荐文章于 2025-09-11 15:05:40 发布

原创最新推荐文章于 2025-09-11 15:05:40 发布 · 2k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger2 #java #spring #api

本文介绍如何在Java API中使用SpringDoc Swagger展示自定义枚举，并解决枚举值显示格式问题，包括加入OpenApiCustomizer和调整Swagger UI样式。

背景：

在java中我们需要用到大量的自定义enum class，而如果想要把这enum 作为一个API的有可能返回值（List of Values），那我们有时候就需要把这些enum class加入到swagger ui 中，同时把enum列出来。

前提条件：

enum 加入到springdoc swagger Schema，自定义enum并加入注解

@Schema(enumAsRef = true）

example：

@AllArgsConstructor
@JsonFormat(shape = JsonFormat.Shape.OBJECT)
@Schema(enumAsRef = true,
        name = "ResponseHeaderMessages",
        description = "List of Values of Standard API Response Body Header",
        title = "List of Values of Standard API Response Body Header"
)
public enum VOUC_API_MESSAGE implements Serializable

添加eunm

如果enum并非API返回值，enum就不能被swagger加入到Schema或Models中，这时候就需要自定义OpenApiCustomiser。在OpenAPI Config 加入以下自定义Bean 用作添加全局可能API返回和自定义enum

@Bean
    public OpenApiCustomiser customerGlobalOpenApiCustomizer() {
        return openApi -> {
            if(openApi != null) {
                openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> {
                    ApiResponses apiResponses = operation.getResponses();
                    Content content = new Content();
                    MediaType mediaType = new MediaType();
                    mediaType.setSchema(openApi.getComponents().getSchemas().get(VoucResponseMessage.class.getSimpleName()));
                    content.addMediaType(org.springframework.http.MediaType.APPLICATION_JSON_VALUE, mediaType);
                    ApiResponse apiResponse = new ApiResponse().description("Common Unauthorized Error").content(content);
                    ApiResponse notFoundApiResponse = new ApiResponse().description("Common Not Found Error").content(content);
                    apiResponses.addApiResponse(String.valueOf(HttpStatus.UNAUTHORIZED.value()), apiResponse);
                    apiResponses.addApiResponse(String.valueOf(HttpStatus.NOT_FOUND.value()), notFoundApiResponse);
                }));
//添加enum Schema                
openApi.getComponents().getSchemas().putAll(ModelConverters.getInstance().readAll(VOUC_API_MESSAGE.class));
            }
        };
    }

enum列值问题

一般enum列值swagger只会用到enum value name。

如果enum比较复杂，而且作为json object 返回到API中，这时候我们需要加入enum的toString方法。

- @JsonValue 将被swagger ModelResolver 用到

    @Override
    @JsonValue
    public String toString() {
        return "{" +
                "code:" + code +
                ", strCode:'" + strCode + '\'' +
                ", httpStatus:" + httpStatus +
                ", message:'" + message + '\'' +
                "}";
    }

经过以上步骤，我们就可以把自定义的enum加入到springdoc 或 swagger中。但是这时候就会发现swagger显示enum值就会全部显示在同一行，或者根本就没有分行。

enum line break解决方法

1. 在enum toString 方法中加入 line break 符号

    @Override
    @JsonValue
    public String toString() {
        return "\r\n{" + //Line break 符号
                "code:" + code +
                ", strCode:'" + strCode + '\'' +
                ", httpStatus:" + httpStatus +
                ", message:'" + message + '\'' +
                "}";
    }

2. 引用自定义的swagger-ui.css 并修改一下css （white-space: pre; 加入到 prop-enum)

.swagger-ui .prop-enum {
    display: block;
    # add below line
    white-space: pre;
}

这样我们的enum列值就会完美显示出来