使用
我有一个Spring Boot应用程序，使用springdoc-openapi为我的控制器生成Swagger API文档。JSON请求/响应中使用的一个枚举具有与其value/toString()不同的JSON表示。这是使用Jackson@JsonValue注释实现的:
public enum Suit {
HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");
@JsonValue
private final String jsonValue;
Suit(String jsonValue) { this.jsonValue = jsonValue; }
}
但是，生成的Swagger API文档在列出枚举值时使用枚举值(特别是toString()的值)而不是JSON表示(每个@JsonValue):
{
"openapi": "3.0.1",
"info": { "title": "OpenAPI definition", "version": "v0" },
"servers": [
{ "url": "http://localhost:8080", "description": "Generated server url" }
],
"paths": { ... },
"components": {
"schemas": {
"PlayingCard": {
"type": "object",
"properties": {
"suit": {
"type": "string",
"enum": [ "Hearts", "Diamonds", "Clubs", "Spades" ]
},
"value": { "type": "integer", "format": "int32" }
}
}
}
}
}
在springdoc-openapi项目中有一个关闭的问题#1101，该问题要求允许@JsonValue影响enum序列化。但是，由于没有提交PR，因此该问题已关闭。
我怎么能得到枚举列表匹配实际的JSON类型接受/返回的REST端点，而不是toString()值?
我解决这个问题的第一个想法是使用Swagger Core的@Schema(allowableValues = {...}]注释。然而，无论是由于bug还是由于设计，这会增加值列表，而不是替换它:
@Schema(allowableValues = {"Hearts", "Diamonds", "Clubs", "Spades"})
public enum Suit {
HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");
// ...
}
"suit": {
"type": "string",
"enum": [
"HEARTS",
"DIAMONDS",
"CLUBS",
"SPADES",
"Hearts",
"Diamonds",
"Clubs",
"Spades"
]
}
plugins {
id 'org.springframework.boot' version '2.5.3'
id 'io.spring.dependency-management' version '1.0.11.RELEASE'
id 'java'
}
sourceCompatibility = '11'
repositories {
mavenCentral()
}
dependencies {
implementation 'io.swagger.core.v3:swagger-annotations:2.1.10'
implementation 'org.springdoc:springdoc-openapi-ui:1.5.10'
implementation 'org.springframework.boot:spring-boot-starter-web'
}
package com.example.springdoc;
import com.fasterxml.jackson.annotation.JsonValue;
public class PlayingCard {
private Suit suit;
private Integer value;
public Suit getSuit() { return suit; }
public void setSuit(Suit suit) { this.suit = suit; }
public Integer getValue() { return value; }
public void setValue(Integer value) { this.value = value; }
public enum Suit {
HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");
@JsonValue
private final String jsonValue;
Suit(String jsonValue) { this.jsonValue = jsonValue; }
}
}
package com.example.springdoc;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/playingCard")
public class PlayingCardController {
@PostMapping
public PlayingCard echo(@RequestBody PlayingCard card) {
return card;
}
}
Swagger URL:http://localhost:8080/v3/api-docs
这是由于2.2.5之前版本的Swagger Core中的bug #3998。在这些版本的库中，@JsonValue在处理公共方法时可以正确处理，但在处理字段时则不能。升级到2.2.5版本或更高版本的Swagger Core将使示例按预期工作，而无需修改。
或者，对于2.2.5之前的Swagger Core版本，添加一个公共访问方法将会达到预期的效果:
public enum Suit {
HEARTS("Hearts"), DIAMONDS("Diamonds"), CLUBS("Clubs"), SPADES("Spades");
private final String jsonValue;
Suit(String jsonValue) { this.jsonValue = jsonValue; }
@JsonValue
public String getJsonValue() {
return jsonValue;
}
}
可以创建一个PropertyCustomizerSpring bean来定制该属性。这既可以针对特定的枚举类型，也可以针对全局的所有枚举。
带有显式列表的特定于类型的定制器
以下自定义器将显式设置特定枚举类型的枚举值:
import com.fasterxml.jackson.databind.JavaType;
import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.media.StringSchema;
import org.springdoc.core.customizers.PropertyCustomizer;
import org.springframework.stereotype.Component;
import java.util.List;
@Component
public class SuitPropertyCustomizer implements PropertyCustomizer {
@Override
public Schema customize(Schema property, AnnotatedType type) {
if (property instanceof StringSchema && isSuit(type)) {
property.setEnum(List.of("Hearts", "Diamonds", "Clubs", "Spades"));
}
return property;
}
private boolean isSuit(AnnotatedType type) {
return type.getType() instanceof JavaType t
&& t.isTypeOrSubTypeOf(Suit.class);
}
}
使用@JsonValue
的全局enum自定义器下面的自定义器将对所有enum类型使用Jackson String表示，这意味着@JsonValue注释将在适当的地方使用。
import com.fasterxml.jackson.databind.JavaType;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.util.Json;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.media.StringSchema;
import org.springdoc.core.customizers.PropertyCustomizer;
import org.springframework.stereotype.Component;
import java.util.Arrays;
import java.util.stream.Collectors;
@Component
public class EnumValuePropertyCustomizer implements PropertyCustomizer {
@Override
public Schema customize(Schema property, AnnotatedType type) {
if (property instanceof StringSchema && isEnumType(type)) {
ObjectMapper objectMapper = Json.mapper();
property.setEnum(Arrays.stream(((JavaType) type.getType()).getRawClass().getEnumConstants())
.map(e -> objectMapper.convertValue(e, String.class))
.collect(Collectors.toList()));
}
return property;
}
private boolean isEnumType(AnnotatedType type) {
return type.getType() instanceof JavaType t && t.getType().isEnumType();
}
}
一个解决方案是用@JsonProperty代替@JsonValue的实现:
public enum Suit {
@JsonProperty("Hearts") HEARTS,
@JsonProperty("Diamonds") DIAMONDS,
@JsonProperty("Clubs") CLUBS,
@JsonProperty("Spades") SPADES;
}
注意，如果在编程上需要该值，这确实会导致一些重复，因为它既需要在@JsonProperty中指定，也需要在enum上指定一个值。