Skip to content

Commit

Permalink
javadoc for class attribute ignored when in EntityModel. Fixes #2320
Browse files Browse the repository at this point in the history
  • Loading branch information
@bnasslahsen
bnasslahsen committed Oct 15, 2023
1 parent b0b94c3 commit d51b98a
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 18 deletions.
51 changes: 38 additions & 13 deletions ...tarter-common/src/main/java/org/springdoc/core/customizers/JavadocPropertyCustomizer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,23 @@
import java.beans.Introspector;
import java.beans.PropertyDescriptor;
import java.lang.reflect.Field;
import java.util.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;

import com.fasterxml.jackson.databind.JavaType;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.introspect.SimpleMixInResolver;
import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.ModelConverterContextImpl;
import io.swagger.v3.core.util.AnnotationsUtils;
import io.swagger.v3.oas.annotations.media.SchemaProperty;
import io.swagger.v3.oas.models.media.Schema;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.reflect.FieldUtils;
Expand All @@ -48,17 +58,19 @@

/**
* The type Javadoc property customizer.
*
* @author bnasslahsen
*/
public record JavadocPropertyCustomizer(JavadocProvider javadocProvider,
ObjectMapperProvider objectMapperProvider)
implements ModelConverter {

private static final Logger LOGGER = LoggerFactory.getLogger(DelegatingMethodParameter.class);

/**
* Instantiates a new Javadoc property customizer.
*
* @param javadocProvider the javadoc provider
* @param javadocProvider the javadoc provider
* @param objectMapperProvider the object mapper provider
*/
public JavadocPropertyCustomizer {
Expand All @@ -67,9 +79,9 @@ public record JavadocPropertyCustomizer(JavadocProvider javadocProvider,
/**
* Resolve schema.
*
* @param type the type
* @param type the type
* @param context the context
* @param chain the chain
* @param chain the chain
* @return the schema
*/
@Override
Expand All @@ -83,18 +95,30 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
List<PropertyDescriptor> clsProperties = new ArrayList<>();
try {
clsProperties = Arrays.asList(Introspector.getBeanInfo(cls).getPropertyDescriptors());
} catch (IntrospectionException ignored) {
}
catch (IntrospectionException ignored) {
LOGGER.warn(ignored.getMessage());
}
if (!CollectionUtils.isEmpty(fields) || !CollectionUtils.isEmpty(clsProperties)) {
if (!type.isSchemaProperty()) {
Schema existingSchema = context.resolve(type);
setJavadocDescription(cls, fields, clsProperties, existingSchema);
setJavadocDescription(cls, fields, clsProperties, existingSchema, false);
}
else if (resolvedSchema != null && resolvedSchema.get$ref() != null && resolvedSchema.get$ref().contains(AnnotationsUtils.COMPONENTS_REF)) {
String schemaName = resolvedSchema.get$ref().substring(21);
Schema existingSchema = context.getDefinedModels().get(schemaName);
setJavadocDescription(cls, fields, clsProperties, existingSchema);
setJavadocDescription(cls, fields, clsProperties, existingSchema, false);
}
else {
try {
Field processedTypesField = FieldUtils.getDeclaredField(ModelConverterContextImpl.class, "processedTypes", true);
Set<AnnotatedType> processedType = (Set<AnnotatedType>) processedTypesField.get(context);
if(processedType.contains(type))
setJavadocDescription(cls, fields, clsProperties, resolvedSchema, true);
}
catch (IllegalAccessException e) {
LOGGER.warn(e.getMessage());
}
}
}
return resolvedSchema;
Expand All @@ -106,14 +130,15 @@ else if (resolvedSchema != null && resolvedSchema.get$ref() != null && resolvedS
/**
* Sets javadoc description.
*
* @param cls the cls
* @param fields the fields
* @param clsProperties the bean properties of cls
* @param existingSchema the existing schema
* @param cls the cls
* @param fields the fields
* @param clsProperties the bean properties of cls
* @param existingSchema the existing schema
* @param isProcessedType the is processed type
*/
public void setJavadocDescription(Class<?> cls, List<Field> fields, List<PropertyDescriptor> clsProperties, Schema existingSchema) {
public void setJavadocDescription(Class<?> cls, List<Field> fields, List<PropertyDescriptor> clsProperties, Schema existingSchema, boolean isProcessedType) {
if (existingSchema != null) {
if (StringUtils.isBlank(existingSchema.getDescription())) {
if (StringUtils.isBlank(existingSchema.getDescription()) && !isProcessedType) {
String classJavadoc = javadocProvider.getClassJavadoc(cls);
if (StringUtils.isNotBlank(classJavadoc)) {
existingSchema.setDescription(classJavadoc);
Expand Down
2 changes: 1 addition & 1 deletion ...adoc-tests/src/test/java/test/org/springdoc/api/app172/JavadocPropertyCustomizerTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ void ifRecordObjectShouldGetField() throws IOException, ClassNotFoundException,
.addProperty("name", new StringSchema().name("name"));

List<PropertyDescriptor> propertyDescriptors = Arrays.asList(Introspector.getBeanInfo(cls).getPropertyDescriptors());
javadocPropertyCustomizer.setJavadocDescription(cls, fields, propertyDescriptors, existingSchema);
javadocPropertyCustomizer.setJavadocDescription(cls, fields, propertyDescriptors, existingSchema,false);

assertEquals("Record Object", existingSchema.getDescription());
Map<String, Schema> properties = existingSchema.getProperties();
Expand Down
8 changes: 6 additions & 2 deletions ...oc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/resources/results/app105-3.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -546,10 +546,12 @@
"properties": {
"id": {
"type": "integer",
"description": "The Id.",
"format": "int64"
},
"name": {
"type": "string"
"type": "string",
"description": "The Name."
}
}
},
Expand Down Expand Up @@ -623,10 +625,12 @@
"properties": {
"id": {
"type": "integer",
"description": "The Id.",
"format": "int64"
},
"name": {
"type": "string"
"type": "string",
"description": "The Name."
}
}
}
Expand Down
8 changes: 6 additions & 2 deletions springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/resources/results/app2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1156,10 +1156,12 @@
"properties": {
"id": {
"type": "integer",
"description": "The Id.",
"format": "int64"
},
"name": {
"type": "string"
"type": "string",
"description": "The Name."
}
}
},
Expand Down Expand Up @@ -1214,10 +1216,12 @@
"properties": {
"id": {
"type": "integer",
"description": "The Id.",
"format": "int64"
},
"name": {
"type": "string"
"type": "string",
"description": "The Name."
}
}
},
Expand Down

0 comments on commit d51b98a

Please sign in to comment.