Merge pull request #836 from linwumingshi/fix/enum-format-number

fix(openapi): 🐛 support @jsonformat(shape = JsonFormat.Shape.NUMBER) annotation for enum types example

Author: shalousun

src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java

@@ -40,7 +40,8 @@
 import java.util.*;
 import java.util.stream.Collectors;
 
-import static com.ly.doc.constants.DocGlobalConstants.*;
+import static com.ly.doc.constants.DocGlobalConstants.OPENAPI_2_COMPONENT_KRY;
+import static com.ly.doc.constants.DocGlobalConstants.OPENAPI_3_COMPONENT_KRY;
 
 
 /**
@@ -162,6 +163,7 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, ApiSchema<ApiDoc> api
      * @param apiConfig    ApiConfig
      * @param apiMethodDoc Method
      * @param apiDoc       ApiDoc
+     * @param apiExceptionStatuses Exception status list
      * @return Map of path urls
      */
     public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List<ApiExceptionStatus> apiExceptionStatuses) {

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

@@ -191,7 +191,10 @@ public static List<ApiParam> buildParams(String className, String pre, int level
                         && (customRequestField.isIgnore()) && !isResp) {
                     continue;
                 }
+                // the param type from @JsonFormat
                 String fieldJsonFormatType = null;
+                // the param value from @JsonFormat
+                String fieldJsonFormatValue = null;
                 // has Annotation @JsonSerialize And using ToStringSerializer
                 boolean toStringSerializer = false;
                 for (JavaAnnotation annotation : javaAnnotations) {
@@ -237,6 +240,7 @@ public static List<ApiParam> buildParams(String className, String pre, int level
                         }
                     } else if (DocAnnotationConstants.JSON_FORMAT.equals(simpleAnnotationName)) {
                         fieldJsonFormatType = DocUtil.processFieldTypeNameByJsonFormat(isShowJavaType, subTypeName, annotation);
+                        fieldJsonFormatValue = DocUtil.getJsonFormatString(field, annotation);
                     }
                 }
                 comment.append(JavaFieldUtil.getJsrComment(apiConfig.isShowValidation(), classLoader, javaAnnotations));
@@ -300,10 +304,16 @@ public static List<ApiParam> buildParams(String className, String pre, int level
                 }
                 if (JavaClassValidateUtil.isPrimitive(subTypeName)) {
                     if (StringUtil.isEmpty(fieldValue)) {
-                        fieldValue = StringUtil.removeQuotes(DocUtil.getValByTypeAndFieldName(subTypeName, field.getName()));
+                        fieldValue = StringUtil.isNotEmpty(fieldJsonFormatValue)
+                                ? fieldJsonFormatValue
+                                : StringUtil.removeQuotes(DocUtil.getValByTypeAndFieldName(subTypeName, field.getName()));
                     }
-                    ApiParam param = ApiParam.of().setClassName(className).setField(pre + fieldName);
-                    param.setPid(pid).setMaxLength(maxLength).setValue(fieldValue);
+
+                    ApiParam param = ApiParam.of().setClassName(className)
+                            .setField(pre + fieldName)
+                            .setPid(pid)
+                            .setMaxLength(maxLength)
+                            .setValue(fieldValue);
                     param.setId(atomicOrDefault(atomicInteger, paramList.size() + param.getPid() + 1));
                     String processedType = (isResp && toStringSerializer) ? "string" : StringUtil.isNotEmpty(fieldJsonFormatType)
                             ? fieldJsonFormatType
@@ -313,7 +323,7 @@ public static List<ApiParam> buildParams(String className, String pre, int level
                     // handle param
                     commonHandleParam(paramList, param, isRequired, comment.toString(), since, strRequired);
 
-                    JavaClass enumClass = ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap);
+                    JavaClass enumClass = ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap, fieldJsonFormatValue);
                     if (Objects.nonNull(enumClass)) {
                         String enumClassComment = DocGlobalConstants.EMPTY;
                         if (StringUtil.isNotEmpty(enumClass.getComment())) {
@@ -370,7 +380,7 @@ public static List<ApiParam> buildParams(String className, String pre, int level
                     JavaClass javaClass = field.getType();
                     if (javaClass.isEnum()) {
                         comment.append(handleEnumComment(javaClass, projectBuilder));
-                        ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap);
+                        ParamUtil.handleSeeEnum(param, field, projectBuilder, jsonRequest, tagsMap, fieldJsonFormatValue);
                         // hand Param
                         commonHandleParam(paramList, param, isRequired, comment + appendComment, since, strRequired);
                     } else if (JavaClassValidateUtil.isCollection(subTypeName) || JavaClassValidateUtil.isArray(subTypeName)) {

src/main/java/com/ly/doc/utils/ParamUtil.java

@@ -10,15 +10,32 @@
 import com.thoughtworks.qdox.model.JavaField;
 
 import java.util.*;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
 
 /**
  * @author <a href="mailto:cqmike0315@gmail.com">chenqi</a>
  * @version 1.0
  */
 public class ParamUtil {
 
+    /**
+     * Handles enum types in API parameters.
+     * <p>
+     * This method is primarily used to process enum types, setting the corresponding parameter type, value, and enumeration information in the ApiParam object.
+     * If the enum has a @JsonFormat annotation with a shape attribute value of NUMBER, the value is processed accordingly.
+     * Additionally, it supports setting mock values for parameters through tag mappings.
+     *
+     * @param param           The ApiParam object, used to store parameter information.
+     * @param javaField       The JavaField object, representing the field of a class, used to obtain the type and other information of the field.
+     * @param builder         The ProjectDocConfigBuilder object, used to obtain configuration information for generating documentation.
+     * @param jsonRequest     A boolean value indicating whether the request is in JSON format, used to determine how to obtain the enum value.
+     * @param tagsMap         A map containing tag names and their descriptions, used to override parameter values with mock data.
+     * @param jsonFormatValue The value of the @JsonFormat annotation's shape attribute, used to handle special cases of numeric enums.
+     * @return Returns the processed JavaClass object representing the enum, or null if the input field is not an enum.
+     */
     public static JavaClass handleSeeEnum(ApiParam param, JavaField javaField, ProjectDocConfigBuilder builder, boolean jsonRequest,
-                                          Map<String, String> tagsMap) {
+                                          Map<String, String> tagsMap, String jsonFormatValue) {
         JavaClass seeEnum = JavaClassUtil.getSeeEnum(javaField, builder);
         if (Objects.isNull(seeEnum)) {
             return null;
@@ -32,6 +49,13 @@ public static JavaClass handleSeeEnum(ApiParam param, JavaField javaField, Proje
         param.setValue(StringUtil.removeDoubleQuotes(String.valueOf(value)));
         param.setEnumValues(JavaClassUtil.getEnumValues(seeEnum));
         param.setEnumInfo(JavaClassUtil.getEnumInfo(seeEnum, builder));
+        // If the @JsonFormat annotation's shape attribute value is specified, use it as the parameter value
+        if (StringUtil.isNotEmpty(jsonFormatValue)) {
+            param.setValue(jsonFormatValue);
+            param.setEnumValues(IntStream.rangeClosed(0, param.getEnumValues().size() - 1)
+                    .mapToObj(Integer::toString).collect(Collectors.toList()));
+        }
+        // If the tagsMap contains a mock tag and the value is not empty, use the value of the mock tag as the parameter value
         // Override old value
         if (tagsMap.containsKey(DocTags.MOCK) && StringUtil.isNotEmpty(tagsMap.get(DocTags.MOCK))) {
             param.setValue(tagsMap.get(DocTags.MOCK));