Skip to content
This repository was archived by the owner on Dec 4, 2025. It is now read-only.

Commit a5faf28

Browse files
linwumingshilinwumingshi
committed
fix: 🐛 correct example value generation for enums annotated with @JsonValue
- Issue: When an enum property or method is annotated with `@JsonValue`, the generated example value should reflect the annotated method’s return value instead of the enum name. - Cause: The example generation logic did not recognize the `@JsonValue` annotation, resulting in the enum name being used as the example value. - Fix: Updated the example generation logic to prioritize the value returned by methods annotated with @jsonvalue.
1 parent dd572f8 commit a5faf28

11 files changed

Lines changed: 348 additions & 63 deletions

File tree

‎pom.xml‎

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,28 @@
3232
<url>https://github.com/shalousun</url>
3333
</developer>
3434
</developers>
35+
3536
<properties>
37+
<java.version>1.8</java.version>
3638
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
3739
<junit.jupiter.version>5.11.3</junit.jupiter.version>
40+
<beetl.version>3.17.0.RELEASE</beetl.version>
41+
<common-util.version>2.2.7</common-util.version>
42+
<qdox.version>2.0.3.4</qdox.version>
43+
<datafaker.version>1.4.0</datafaker.version>
44+
<gson.version>2.11.0</gson.version>
45+
<eclipse.jgit.version>5.13.3.202401111512-r</eclipse.jgit.version>
46+
<slf4j-api.version>2.0.16</slf4j-api.version>
47+
48+
<!-- plugin version -->
49+
<maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
50+
<maven-source-plugin.version>3.3.1</maven-source-plugin.version>
51+
<maven-javadoc-plugin.version>3.11.1</maven-javadoc-plugin.version>
52+
<spring-javaformat-maven-plugin.version>0.0.43</spring-javaformat-maven-plugin.version>
53+
<central-publishing-maven-plugin.version>0.6.0</central-publishing-maven-plugin.version>
54+
<maven-gpg-plugin.version>3.2.7</maven-gpg-plugin.version>
3855
</properties>
56+
3957
<dependencies>
4058
<dependency>
4159
<groupId>org.junit.jupiter</groupId>
@@ -46,37 +64,37 @@
4664
<dependency>
4765
<groupId>com.ibeetl</groupId>
4866
<artifactId>beetl</artifactId>
49-
<version>3.17.0.RELEASE</version>
67+
<version>${beetl.version}</version>
5068
</dependency>
5169
<dependency>
5270
<groupId>com.ly.smart-doc</groupId>
5371
<artifactId>qdox</artifactId>
54-
<version>2.0.3.4</version>
72+
<version>${qdox.version}</version>
5573
</dependency>
5674
<dependency>
5775
<groupId>net.datafaker</groupId>
5876
<artifactId>datafaker</artifactId>
59-
<version>1.4.0</version>
77+
<version>${datafaker.version}</version>
6078
</dependency>
6179
<dependency>
6280
<groupId>io.github.shalousun</groupId>
6381
<artifactId>common-util</artifactId>
64-
<version>2.2.6</version>
82+
<version>${common-util.version}</version>
6583
</dependency>
6684
<dependency>
6785
<groupId>com.google.code.gson</groupId>
6886
<artifactId>gson</artifactId>
69-
<version>2.11.0</version>
87+
<version>${gson.version}</version>
7088
</dependency>
7189
<dependency>
7290
<groupId>org.slf4j</groupId>
7391
<artifactId>slf4j-api</artifactId>
74-
<version>2.0.16</version>
92+
<version>${slf4j-api.version}</version>
7593
</dependency>
7694
<dependency>
7795
<groupId>org.eclipse.jgit</groupId>
7896
<artifactId>org.eclipse.jgit</artifactId>
79-
<version>5.13.3.202401111512-r</version>
97+
<version>${eclipse.jgit.version}</version>
8098
</dependency>
8199
</dependencies>
82100
<build>
@@ -85,18 +103,18 @@
85103
<plugin>
86104
<groupId>org.apache.maven.plugins</groupId>
87105
<artifactId>maven-compiler-plugin</artifactId>
88-
<version>3.13.0</version>
106+
<version>${maven-compiler-plugin.version}</version>
89107
<configuration>
90-
<source>1.8</source>
91-
<target>1.8</target>
108+
<source>${java.version}</source>
109+
<target>${java.version}</target>
92110
<encoding>UTF-8</encoding>
93111
</configuration>
94112
</plugin>
95113
<!-- Source -->
96114
<plugin>
97115
<groupId>org.apache.maven.plugins</groupId>
98116
<artifactId>maven-source-plugin</artifactId>
99-
<version>3.3.1</version>
117+
<version>${maven-source-plugin.version}</version>
100118
<executions>
101119
<execution>
102120
<phase>package</phase>
@@ -110,7 +128,7 @@
110128
<plugin>
111129
<groupId>org.apache.maven.plugins</groupId>
112130
<artifactId>maven-javadoc-plugin</artifactId>
113-
<version>3.11.1</version>
131+
<version>${maven-javadoc-plugin.version}</version>
114132
<executions>
115133
<execution>
116134
<phase>package</phase>
@@ -124,7 +142,7 @@
124142
<plugin>
125143
<groupId>io.spring.javaformat</groupId>
126144
<artifactId>spring-javaformat-maven-plugin</artifactId>
127-
<version>0.0.43</version>
145+
<version>${spring-javaformat-maven-plugin.version}</version>
128146
<executions>
129147
<execution>
130148
<phase>validate</phase>
@@ -143,10 +161,10 @@
143161
<id>release</id>
144162
<build>
145163
<plugins>
146-
<plugin>
164+
<plugin>
147165
<groupId>org.sonatype.central</groupId>
148166
<artifactId>central-publishing-maven-plugin</artifactId>
149-
<version>0.6.0</version>
167+
<version>${central-publishing-maven-plugin.version}</version>
150168
<extensions>true</extensions>
151169
<configuration>
152170
<publishingServerId>central-ly</publishingServerId>
@@ -156,7 +174,7 @@
156174
<plugin>
157175
<groupId>org.apache.maven.plugins</groupId>
158176
<artifactId>maven-gpg-plugin</artifactId>
159-
<version>3.2.7</version>
177+
<version>${maven-gpg-plugin.version}</version>
160178
<executions>
161179
<execution>
162180
<id>sign-artifacts</id>

‎src/main/java/com/ly/doc/helper/ParamsBuildHelper.java‎

Lines changed: 44 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,16 +29,36 @@
2929
import com.ly.doc.constants.ParamTypeConstants;
3030
import com.ly.doc.extension.json.PropertyNameHelper;
3131
import com.ly.doc.extension.json.PropertyNamingStrategies;
32-
import com.ly.doc.model.*;
33-
import com.ly.doc.utils.*;
32+
import com.ly.doc.model.ApiConfig;
33+
import com.ly.doc.model.ApiDataDictionary;
34+
import com.ly.doc.model.ApiParam;
35+
import com.ly.doc.model.CustomField;
36+
import com.ly.doc.model.CustomFieldInfo;
37+
import com.ly.doc.model.DocJavaField;
38+
import com.ly.doc.model.FieldJsonAnnotationInfo;
39+
import com.ly.doc.model.torna.EnumInfoAndValues;
40+
import com.ly.doc.utils.DocClassUtil;
41+
import com.ly.doc.utils.DocUtil;
42+
import com.ly.doc.utils.JavaClassUtil;
43+
import com.ly.doc.utils.JavaClassValidateUtil;
44+
import com.ly.doc.utils.JavaFieldUtil;
45+
import com.ly.doc.utils.ParamUtil;
3446
import com.power.common.model.EnumDictionary;
3547
import com.power.common.util.StringUtil;
3648
import com.thoughtworks.qdox.model.JavaAnnotation;
3749
import com.thoughtworks.qdox.model.JavaClass;
3850
import com.thoughtworks.qdox.model.JavaField;
3951
import org.apache.commons.lang3.StringUtils;
4052

41-
import java.util.*;
53+
import java.util.ArrayList;
54+
import java.util.Collections;
55+
import java.util.HashMap;
56+
import java.util.LinkedHashMap;
57+
import java.util.List;
58+
import java.util.Map;
59+
import java.util.Objects;
60+
import java.util.Optional;
61+
import java.util.Set;
4262
import java.util.concurrent.atomic.AtomicInteger;
4363
import java.util.stream.Collectors;
4464

@@ -245,8 +265,8 @@ private static List<ApiParam> processFields(String className, String pre, int le
245265
// handle extension
246266
Map<String, String> extensions = DocUtil.getCommentsByTag(field.getTagsByName(DocTags.EXTENSION),
247267
DocTags.EXTENSION);
248-
Map<String, Object> extensionParams = new HashMap<>();
249-
if (extensions != null && !extensions.isEmpty()) {
268+
Map<String, Object> extensionParams = new HashMap<>(extensions.size());
269+
if (!extensions.isEmpty()) {
250270
extensions.forEach((k, v) -> extensionParams.put(k, DocUtil.detectTagValue(v)));
251271
}
252272

@@ -367,8 +387,8 @@ private static List<ApiParam> processFields(String className, String pre, int le
367387
// handle param
368388
commonHandleParam(paramList, param, isRequired, comment.toString(), since, strRequired);
369389

370-
JavaClass enumClass = ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap,
371-
fieldJsonFormatValue);
390+
JavaClass enumClass = ParamUtil.handleSeeEnum(param, field, projectBuilder, isResp || jsonRequest,
391+
tagsMap, fieldJsonFormatValue);
372392
if (Objects.nonNull(enumClass)) {
373393
String enumClassComment = DocGlobalConstants.EMPTY;
374394
if (StringUtil.isNotEmpty(enumClass.getComment())) {
@@ -431,7 +451,8 @@ private static List<ApiParam> processFields(String className, String pre, int le
431451
JavaClass javaClass = field.getType();
432452
if (javaClass.isEnum()) {
433453
comment.append(handleEnumComment(javaClass, projectBuilder));
434-
ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap, fieldJsonFormatValue);
454+
ParamUtil.handleSeeEnum(param, field, projectBuilder, isResp || jsonRequest, tagsMap,
455+
fieldJsonFormatValue);
435456
// hand Param
436457
commonHandleParam(paramList, param, isRequired, comment + appendComment, since, strRequired);
437458
}
@@ -484,10 +505,12 @@ else if (JavaClassValidateUtil.isCollection(subTypeName)
484505
if (!simpleName.equals(gName)) {
485506
JavaClass arraySubClass = projectBuilder.getJavaProjectBuilder().getClassByName(gName);
486507
if (arraySubClass.isEnum()) {
487-
Object value = JavaClassUtil.getEnumValue(arraySubClass, projectBuilder, Boolean.FALSE);
488-
param.setValue("[\"" + value + "\"]")
489-
.setEnumInfo(JavaClassUtil.getEnumInfo(arraySubClass, projectBuilder))
490-
.setEnumValues(JavaClassUtil.getEnumValues(arraySubClass));
508+
EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(arraySubClass,
509+
projectBuilder, Boolean.FALSE);
510+
if (Objects.nonNull(enumInfoAndValue)) {
511+
param.setValue("[\"" + enumInfoAndValue.getValue() + "\"]")
512+
.setEnumInfoAndValues(enumInfoAndValue);
513+
}
491514
}
492515
else if (gName.length() == 1) {
493516
// handle generic
@@ -782,6 +805,15 @@ private static void commonHandleParam(List<ApiParam> paramList, ApiParam param,
782805
paramList.add(param);
783806
}
784807

808+
/**
809+
* Handles the generation of comments for enum types in a Java class. If the class is
810+
* an enum, it generates the corresponding enum comment based on the project
811+
* configuration; otherwise, it returns an empty comment string.
812+
* @param javaClass The JavaClass object containing class information.
813+
* @param projectBuilder The ProjectDocConfigBuilder object containing project
814+
* configuration information.
815+
* @return The generated enum comment string.
816+
*/
785817
public static String handleEnumComment(JavaClass javaClass, ProjectDocConfigBuilder projectBuilder) {
786818
String comment = "";
787819
if (!javaClass.isEnum()) {

‎src/main/java/com/ly/doc/model/ApiParam.java‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,14 @@
2020
*/
2121
package com.ly.doc.model;
2222

23+
import com.ly.doc.model.torna.EnumInfo;
24+
import com.ly.doc.model.torna.EnumInfoAndValues;
25+
import org.apache.commons.lang3.StringUtils;
26+
2327
import java.util.List;
2428
import java.util.Map;
2529
import java.util.Objects;
2630

27-
import com.ly.doc.model.torna.EnumInfo;
28-
29-
import org.apache.commons.lang3.StringUtils;
30-
3131
import static com.ly.doc.constants.DocGlobalConstants.PARAM_PREFIX;
3232

3333
/**
@@ -111,12 +111,14 @@ public class ApiParam {
111111
private boolean hasItems;
112112

113113
/**
114-
* enum values
114+
* enum values<br>
115+
* Use in openapi api document
115116
*/
116117
private List<String> enumValues;
117118

118119
/**
119-
* enum
120+
* enum Info<br>
121+
* Use in torna api document
120122
*/
121123
private EnumInfo enumInfo;
122124

@@ -340,6 +342,15 @@ public ApiParam setFormat(String format) {
340342
return this;
341343
}
342344

345+
public ApiParam setEnumInfoAndValues(EnumInfoAndValues enumInfoAndValues) {
346+
if (Objects.isNull(enumInfoAndValues)) {
347+
return this;
348+
}
349+
this.enumInfo = enumInfoAndValues.getEnumInfo();
350+
this.enumValues = enumInfoAndValues.getEnumValues();
351+
return this;
352+
}
353+
343354
@Override
344355
public String toString() {
345356
return "ApiParam{" + "className='" + className + '\'' + ", id=" + id + ", field='" + field + '\'' + ", type='"

‎src/main/java/com/ly/doc/model/torna/EnumInfo.java‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,17 +20,35 @@
2020
*/
2121
package com.ly.doc.model.torna;
2222

23+
import java.io.Serializable;
2324
import java.util.List;
2425

2526
/**
27+
* Torna Enum Info
28+
*
2629
* @author xingzi 2021/2/25 12:13
30+
* @since 2.0.9
2731
**/
28-
public class EnumInfo {
32+
public class EnumInfo implements Serializable {
33+
34+
/**
35+
* serialVersionUID
36+
*/
37+
private static final long serialVersionUID = -4902969363646799679L;
2938

39+
/**
40+
* enum name
41+
*/
3042
private String name;
3143

44+
/**
45+
* enum description
46+
*/
3247
private String description;
3348

49+
/**
50+
* enum items
51+
*/
3452
private List<Item> items;
3553

3654
public String getName() {

0 commit comments

Comments
 (0)