Skip to content

Commit aab453f

Browse files
eye-guAias00
andauthored
feat(api-doc): support request parameter parsing for RPC types (Dubbo/SOFA/TARS/gRPC) (#6339)
* feat(api-doc): support request parameter parsing for RPC types (Dubbo/SOFA/TARS/gRPC) * fix license * fix checkstyle exclude generated source * fix checkstyle * fix review * Fix Protobuf field schema parsing logic * fix use common version * chore: trigger CI retest * fix RPC api-doc generation for protobuf nesting --------- Co-authored-by: aias00 <[email protected]>
1 parent 127aa7a commit aab453f

3 files changed

Lines changed: 116 additions & 58 deletions

File tree

‎shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/utils/OpenApiUtils.java‎

Lines changed: 61 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -448,14 +448,13 @@ private static boolean isProtobufEmpty(final Class<?> clazz) {
448448
* Parse protobuf message fields using reflection on getDescriptor().
449449
* Protobuf descriptor types are mapped to OpenAPI types.
450450
*
451-
* @param responseType the response type to populate
452-
* @param clazz the protobuf message class
453-
* @param depth current recursion depth
454-
* @param typeVariableMap type variable map
451+
* @param responseType the response type to populate
452+
* @param clazz the protobuf message class
453+
* @param depth current recursion depth
455454
* @return populated ResponseType
456455
*/
457456
private static ResponseType parseProtobufClass(final ResponseType responseType, final Class<?> clazz,
458-
final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) {
457+
final int depth) {
459458
if (isProtobufEmpty(clazz)) {
460459
responseType.setType("object");
461460
return responseType;
@@ -466,7 +465,7 @@ private static ResponseType parseProtobufClass(final ResponseType responseType,
466465
java.lang.reflect.Method getFieldsMethod = descriptor.getClass().getMethod("getFields");
467466
@SuppressWarnings("unchecked")
468467
List<?> fields = (List<?>) getFieldsMethod.invoke(descriptor);
469-
List<ResponseType> refs = parseProtobufFields(fields, clazz, depth, typeVariableMap);
468+
List<ResponseType> refs = parseProtobufFields(fields, clazz, depth);
470469
responseType.setType("object");
471470
responseType.setRefs(refs);
472471
} catch (Exception e) {
@@ -476,7 +475,7 @@ private static ResponseType parseProtobufClass(final ResponseType responseType,
476475
}
477476

478477
private static List<ResponseType> parseProtobufFields(final List<?> fields, final Class<?> clazz,
479-
final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
478+
final int depth) throws Exception {
480479
List<ResponseType> refs = new ArrayList<>();
481480
java.lang.reflect.Method getNameMethod = null;
482481
java.lang.reflect.Method getTypeMethod = null;
@@ -493,23 +492,22 @@ private static List<ResponseType> parseProtobufFields(final List<?> fields, fina
493492
Object fieldType = getTypeMethod.invoke(field);
494493
boolean isRepeated = (boolean) isRepeatedMethod.invoke(field);
495494
refs.add(parseProtobufField(fieldName, fieldType, isRepeated,
496-
getMessageTypeMethod, field, clazz, depth, typeVariableMap));
495+
getMessageTypeMethod, field, clazz, depth));
497496
}
498497
return refs;
499498
}
500499

501500
private static ResponseType parseProtobufField(final String fieldName, final Object fieldType, final boolean isRepeated,
502501
final java.lang.reflect.Method getMessageTypeMethod, final Object field,
503-
final Class<?> clazz, final int depth,
504-
final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
502+
final Class<?> clazz, final int depth) throws Exception {
505503
if (isRepeated) {
506-
return parseRepeatedProtobufField(fieldName, fieldType, getMessageTypeMethod, field);
504+
return parseRepeatedProtobufField(fieldName, fieldType, getMessageTypeMethod, field, clazz, depth);
507505
}
508506
String fieldTypeName = fieldType.toString();
509507
ResponseType fieldResponse = new ResponseType();
510508
fieldResponse.setName(fieldName);
511509
if ("MESSAGE".equals(fieldTypeName)) {
512-
resolveProtobufMessageField(fieldResponse, getMessageTypeMethod, field, clazz, depth, typeVariableMap);
510+
resolveProtobufMessageField(fieldResponse, getMessageTypeMethod, field, clazz, depth);
513511
} else if ("ENUM".equals(fieldTypeName)) {
514512
fieldResponse.setType("string");
515513
} else {
@@ -520,19 +518,16 @@ private static ResponseType parseProtobufField(final String fieldName, final Obj
520518

521519
private static ResponseType parseRepeatedProtobufField(final String fieldName, final Object fieldType,
522520
final java.lang.reflect.Method getMessageTypeMethod,
523-
final Object field) throws Exception {
521+
final Object field, final Class<?> clazz,
522+
final int depth) throws Exception {
524523
ResponseType arrayType = new ResponseType();
525524
arrayType.setName(fieldName);
526525
arrayType.setType("array");
527526
String fieldTypeName = fieldType.toString();
528527
ResponseType elementType = new ResponseType();
529-
elementType.setName("ITEMS");
528+
elementType.setName("items");
530529
if ("MESSAGE".equals(fieldTypeName)) {
531-
Object msgDescriptor = getMessageTypeMethod.invoke(field);
532-
java.lang.reflect.Method getFullNameMethod = msgDescriptor.getClass().getMethod("getFullName");
533-
String fullMsgName = (String) getFullNameMethod.invoke(msgDescriptor);
534-
elementType.setType("object");
535-
elementType.setDescription(fullMsgName);
530+
resolveProtobufMessageField(elementType, getMessageTypeMethod, field, clazz, depth);
536531
} else {
537532
elementType.setType(mapProtobufTypeToOpenApi(fieldTypeName));
538533
}
@@ -543,8 +538,7 @@ private static ResponseType parseRepeatedProtobufField(final String fieldName, f
543538
private static void resolveProtobufMessageField(final ResponseType fieldResponse,
544539
final java.lang.reflect.Method getMessageTypeMethod,
545540
final Object field, final Class<?> clazz,
546-
final int depth,
547-
final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
541+
final int depth) throws Exception {
548542
Object msgDescriptor = getMessageTypeMethod.invoke(field);
549543
java.lang.reflect.Method getFullNameMethod = msgDescriptor.getClass().getMethod("getFullName");
550544
String fullMsgName = (String) getFullNameMethod.invoke(msgDescriptor);
@@ -553,7 +547,7 @@ private static void resolveProtobufMessageField(final ResponseType fieldResponse
553547
if (depth < 5) {
554548
try {
555549
Class<?> nestedClass = Class.forName(toJavaClassName(clazz, fullMsgName));
556-
List<ResponseType> nestedRefs = parseProtobufClass(new ResponseType(), nestedClass, depth + 1, typeVariableMap).getRefs();
550+
List<ResponseType> nestedRefs = parseProtobufClass(new ResponseType(), nestedClass, depth + 1).getRefs();
557551
if (Objects.nonNull(nestedRefs) && !nestedRefs.isEmpty()) {
558552
fieldResponse.setRefs(nestedRefs);
559553
}
@@ -665,7 +659,7 @@ private static ResponseType parseType(final String name, final Type type, final
665659
private static ResponseType parseClass(final ResponseType responseType, final Class<?> clazz, final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) {
666660
if (clazz.isArray()) {
667661
responseType.setType("array");
668-
responseType.setRefs(Collections.singletonList(parseType("ITEMS", clazz.getComponentType(), depth + 1, typeVariableMap)));
662+
responseType.setRefs(Collections.singletonList(parseType("items", clazz.getComponentType(), depth + 1, typeVariableMap)));
669663
return responseType;
670664
} else if (clazz.isEnum()) {
671665
responseType.setType("string");
@@ -686,13 +680,10 @@ private static ResponseType parseClass(final ResponseType responseType, final Cl
686680
responseType.setType("date");
687681
return responseType;
688682
} else if (isProtobufMessage(clazz)) {
689-
return parseProtobufClass(responseType, clazz, depth, typeVariableMap);
683+
return parseProtobufClass(responseType, clazz, depth);
690684
} else {
691685
List<ResponseType> refs = new ArrayList<>();
692-
for (Field field : clazz.getDeclaredFields()) {
693-
if (Modifier.isStatic(field.getModifiers())) {
694-
continue;
695-
}
686+
for (Field field : collectInstanceFields(clazz)) {
696687
refs.add(parseType(field.getName(), field.getGenericType(), depth + 1, typeVariableMap));
697688
}
698689
responseType.setType("object");
@@ -711,7 +702,7 @@ private static ResponseType parseParameterizedType(final ResponseType responseTy
711702
}
712703
if (Collection.class.isAssignableFrom(rawType)) {
713704
Type actualType = actualTypeArguments[0];
714-
ResponseType elementParam = parseType("ITEMS", actualType, depth + 1, newTypeVariableMap);
705+
ResponseType elementParam = parseType("items", actualType, depth + 1, newTypeVariableMap);
715706
responseType.setRefs(Collections.singletonList(elementParam));
716707
responseType.setType("array");
717708
return responseType;
@@ -728,10 +719,7 @@ private static ResponseType parseParameterizedType(final ResponseType responseTy
728719
return responseType;
729720
} else {
730721
List<ResponseType> refs = new ArrayList<>();
731-
for (Field field : rawType.getDeclaredFields()) {
732-
if (Modifier.isStatic(field.getModifiers())) {
733-
continue;
734-
}
722+
for (Field field : collectInstanceFields(rawType)) {
735723
ResponseType fieldParam = parseType(field.getName(), field.getGenericType(), depth + 1, newTypeVariableMap);
736724
refs.add(fieldParam);
737725
}
@@ -742,7 +730,7 @@ private static ResponseType parseParameterizedType(final ResponseType responseTy
742730
}
743731

744732
private static ResponseType parseGenericArrayType(final ResponseType responseType, final GenericArrayType type, final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) {
745-
responseType.setRefs(Collections.singletonList(parseType("ITEMS", type.getGenericComponentType(), depth + 1, typeVariableMap)));
733+
responseType.setRefs(Collections.singletonList(parseType("items", type.getGenericComponentType(), depth + 1, typeVariableMap)));
746734
responseType.setType("array");
747735
return responseType;
748736
}
@@ -797,13 +785,10 @@ private static Schema parseClassSchema(final Class<?> clazz, final int depth, fi
797785
} else if (Map.class.isAssignableFrom(clazz)) {
798786
return new Schema("object", null);
799787
} else if (isProtobufMessage(clazz)) {
800-
return parseProtobufClassSchema(clazz, depth, typeVariableMap);
788+
return parseProtobufClassSchema(clazz, depth);
801789
} else {
802790
List<Schema> refs = new ArrayList<>();
803-
for (Field field : clazz.getDeclaredFields()) {
804-
if (Modifier.isStatic(field.getModifiers())) {
805-
continue;
806-
}
791+
for (Field field : collectInstanceFields(clazz)) {
807792
Schema fieldSchema = parseSchema(field.getGenericType(), depth + 1, typeVariableMap);
808793
fieldSchema.setName(field.getName());
809794
refs.add(fieldSchema);
@@ -838,10 +823,7 @@ private static Schema parseParameterizedTypeSchema(final ParameterizedType type,
838823
return schema;
839824
} else {
840825
List<Schema> refs = new ArrayList<>();
841-
for (Field field : rawType.getDeclaredFields()) {
842-
if (Modifier.isStatic(field.getModifiers())) {
843-
continue;
844-
}
826+
for (Field field : collectInstanceFields(rawType)) {
845827
Schema fieldSchema = parseSchema(field.getGenericType(), depth + 1, newTypeVariableMap);
846828
fieldSchema.setName(field.getName());
847829
refs.add(fieldSchema);
@@ -852,7 +834,7 @@ private static Schema parseParameterizedTypeSchema(final ParameterizedType type,
852834
}
853835
}
854836

855-
private static Schema parseProtobufClassSchema(final Class<?> clazz, final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) {
837+
private static Schema parseProtobufClassSchema(final Class<?> clazz, final int depth) {
856838
if (isProtobufEmpty(clazz)) {
857839
return new Schema("object", null);
858840
}
@@ -862,7 +844,7 @@ private static Schema parseProtobufClassSchema(final Class<?> clazz, final int d
862844
java.lang.reflect.Method getFieldsMethod = descriptor.getClass().getMethod("getFields");
863845
@SuppressWarnings("unchecked")
864846
List<?> fields = (List<?>) getFieldsMethod.invoke(descriptor);
865-
List<Schema> refs = parseProtobufFieldsSchema(fields, clazz, depth, typeVariableMap);
847+
List<Schema> refs = parseProtobufFieldsSchema(fields, clazz, depth);
866848
Schema schema = new Schema("object", null);
867849
schema.setRefs(refs);
868850
return schema;
@@ -872,7 +854,7 @@ private static Schema parseProtobufClassSchema(final Class<?> clazz, final int d
872854
}
873855

874856
private static List<Schema> parseProtobufFieldsSchema(final List<?> fields, final Class<?> clazz,
875-
final int depth, final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
857+
final int depth) throws Exception {
876858
List<Schema> refs = new ArrayList<>();
877859
java.lang.reflect.Method getNameMethod = null;
878860
java.lang.reflect.Method getTypeMethod = null;
@@ -889,22 +871,21 @@ private static List<Schema> parseProtobufFieldsSchema(final List<?> fields, fina
889871
Object fieldType = getTypeMethod.invoke(field);
890872
boolean isRepeated = (boolean) isRepeatedMethod.invoke(field);
891873
refs.add(parseProtobufFieldSchema(fieldName, fieldType, isRepeated,
892-
getMessageTypeMethod, field, clazz, depth, typeVariableMap));
874+
getMessageTypeMethod, field, clazz, depth));
893875
}
894876
return refs;
895877
}
896878

897879
private static Schema parseProtobufFieldSchema(final String fieldName, final Object fieldType, final boolean isRepeated,
898880
final java.lang.reflect.Method getMessageTypeMethod, final Object field,
899-
final Class<?> clazz, final int depth,
900-
final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
881+
final Class<?> clazz, final int depth) throws Exception {
901882
if (isRepeated) {
902-
return parseRepeatedProtobufFieldSchema(fieldName, fieldType, getMessageTypeMethod, field, clazz, depth, typeVariableMap);
883+
return parseRepeatedProtobufFieldSchema(fieldName, fieldType, getMessageTypeMethod, field, clazz, depth);
903884
}
904885
String fieldTypeName = fieldType.toString();
905886
Schema schema;
906887
if ("MESSAGE".equals(fieldTypeName)) {
907-
schema = resolveProtobufMessageFieldSchema(getMessageTypeMethod, field, clazz, depth, typeVariableMap);
888+
schema = resolveProtobufMessageFieldSchema(getMessageTypeMethod, field, clazz, depth);
908889
} else if ("ENUM".equals(fieldTypeName)) {
909890
schema = new Schema("string", null);
910891
} else {
@@ -917,12 +898,11 @@ private static Schema parseProtobufFieldSchema(final String fieldName, final Obj
917898
private static Schema parseRepeatedProtobufFieldSchema(final String fieldName, final Object fieldType,
918899
final java.lang.reflect.Method getMessageTypeMethod,
919900
final Object field,
920-
final Class<?> clazz, final int depth,
921-
final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
901+
final Class<?> clazz, final int depth) throws Exception {
922902
String fieldTypeName = fieldType.toString();
923903
Schema elementSchema;
924904
if ("MESSAGE".equals(fieldTypeName)) {
925-
elementSchema = resolveProtobufMessageFieldSchema(getMessageTypeMethod, field, clazz, depth, typeVariableMap);
905+
elementSchema = resolveProtobufMessageFieldSchema(getMessageTypeMethod, field, clazz, depth);
926906
} else if ("ENUM".equals(fieldTypeName)) {
927907
elementSchema = new Schema("string", null);
928908
} else {
@@ -937,16 +917,15 @@ private static Schema parseRepeatedProtobufFieldSchema(final String fieldName, f
937917

938918
private static Schema resolveProtobufMessageFieldSchema(final java.lang.reflect.Method getMessageTypeMethod,
939919
final Object field, final Class<?> clazz,
940-
final int depth,
941-
final Map<TypeVariable<?>, Type> typeVariableMap) throws Exception {
920+
final int depth) throws Exception {
942921
Object msgDescriptor = getMessageTypeMethod.invoke(field);
943922
java.lang.reflect.Method getFullNameMethod = msgDescriptor.getClass().getMethod("getFullName");
944923
String fullMsgName = (String) getFullNameMethod.invoke(msgDescriptor);
945924
Schema schema = new Schema("object", null);
946925
if (depth < 5) {
947926
try {
948927
Class<?> nestedClass = Class.forName(toJavaClassName(clazz, fullMsgName));
949-
List<Schema> nestedRefs = parseProtobufClassSchema(nestedClass, depth + 1, typeVariableMap).getRefs();
928+
List<Schema> nestedRefs = parseProtobufClassSchema(nestedClass, depth + 1).getRefs();
950929
if (Objects.nonNull(nestedRefs) && !nestedRefs.isEmpty()) {
951930
schema.setRefs(nestedRefs);
952931
}
@@ -969,6 +948,31 @@ private static String toJavaClassName(final Class<?> contextClass, final String
969948
return protobufFullName.replace('.', '$');
970949
}
971950

951+
/**
952+
* Collect non-static declared instance fields walking up the class hierarchy.
953+
* Fields are ordered subclass-first then superclass, so the generated document
954+
* keeps the declared order of the most specific type. Stops at {@code Object}
955+
* and protobuf base classes (protobuf messages are parsed via descriptor, not
956+
* reflection, so they never reach here).
957+
*
958+
* @param clazz the class to inspect
959+
* @return ordered list of instance fields
960+
*/
961+
private static List<Field> collectInstanceFields(final Class<?> clazz) {
962+
List<Field> fields = new ArrayList<>();
963+
Class<?> current = clazz;
964+
while (Objects.nonNull(current) && current != Object.class && !isProtobufMessage(current)) {
965+
for (Field field : current.getDeclaredFields()) {
966+
if (Modifier.isStatic(field.getModifiers())) {
967+
continue;
968+
}
969+
fields.add(field);
970+
}
971+
current = current.getSuperclass();
972+
}
973+
return fields;
974+
}
975+
972976
private static boolean isDateType(final Class<?> clazz) {
973977
return clazz == Date.class || clazz == LocalDate.class
974978
|| clazz == LocalDateTime.class || clazz == LocalTime.class;

0 commit comments

Comments
 (0)