Skip to content

Commit

Permalink
Support get javadoc description from getter method review
Browse files Browse the repository at this point in the history
  • Loading branch information
bnasslahsen committed Oct 15, 2023
2 parents 1d94e47 + 7dfc405 commit 74b2932
Show file tree
Hide file tree
Showing 12 changed files with 446 additions and 36 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,11 @@

package org.springdoc.core.customizers;

import java.beans.IntrospectionException;
import java.beans.Introspector;
import java.beans.PropertyDescriptor;
import java.lang.reflect.Field;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.*;

import com.fasterxml.jackson.databind.JavaType;
import io.swagger.v3.core.converter.AnnotatedType;
Expand All @@ -38,6 +38,9 @@
import io.swagger.v3.oas.models.media.Schema;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springdoc.core.extractor.DelegatingMethodParameter;
import org.springdoc.core.providers.JavadocProvider;
import org.springdoc.core.providers.ObjectMapperProvider;

Expand All @@ -51,6 +54,7 @@ public record JavadocPropertyCustomizer(JavadocProvider javadocProvider,
ObjectMapperProvider objectMapperProvider)
implements ModelConverter {

private static final Logger LOGGER = LoggerFactory.getLogger(DelegatingMethodParameter.class);
/**
* Instantiates a new Javadoc property customizer.
*
Expand All @@ -76,15 +80,21 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
Class<?> cls = javaType.getRawClass();
Schema<?> resolvedSchema = chain.next().resolve(type, context, chain);
List<Field> fields = FieldUtils.getAllFieldsList(cls);
if (!CollectionUtils.isEmpty(fields)) {
List<PropertyDescriptor> clsProperties = new ArrayList<>();
try {
clsProperties = Arrays.asList(Introspector.getBeanInfo(cls).getPropertyDescriptors());
} 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, existingSchema);
setJavadocDescription(cls, fields, clsProperties, existingSchema);
}
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, existingSchema);
setJavadocDescription(cls, fields, clsProperties, existingSchema);
}
}
return resolvedSchema;
Expand All @@ -96,10 +106,12 @@ 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
*/
private void setJavadocDescription(Class<?> cls, List<Field> fields, Schema existingSchema) {
public void setJavadocDescription(Class<?> cls, List<Field> fields, List<PropertyDescriptor> clsProperties, Schema existingSchema) {
if (existingSchema != null) {
if (StringUtils.isBlank(existingSchema.getDescription())) {
String classJavadoc = javadocProvider.getClassJavadoc(cls);
Expand Down Expand Up @@ -127,6 +139,14 @@ private void setJavadocDescription(Class<?> cls, List<Field> fields, Schema exis
if (StringUtils.isNotBlank(fieldJavadoc))
stringSchemaEntry.getValue().setDescription(fieldJavadoc);
});
if (StringUtils.isBlank(stringSchemaEntry.getValue().getDescription())) {
Optional<PropertyDescriptor> optionalPd = clsProperties.stream().filter(pd -> pd.getName().equals(stringSchemaEntry.getKey())).findAny();
optionalPd.ifPresent(pd1 -> {
String fieldJavadoc = javadocProvider.getMethodJavadocDescription(pd1.getReadMethod());
if (StringUtils.isNotBlank(fieldJavadoc))
stringSchemaEntry.getValue().setDescription(fieldJavadoc);
});
}
});
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* *
* * *
* * * *
* * * * * Copyright 2019-2022 the original author or authors.
* * * * * Copyright 2019-2023 the original author or authors.
* * * * *
* * * * * Licensed under the Apache License, Version 2.0 (the "License");
* * * * * you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -124,31 +124,16 @@ public static MethodParameter[] customize(String[] pNames, MethodParameter[] par
MethodParameter p = parameters[i];
Class<?> paramClass = AdditionalModelsConverter.getParameterObjectReplacement(p.getParameterType());

if (!MethodParameterPojoExtractor.isSimpleType(paramClass) && (p.hasParameterAnnotation(ParameterObject.class) || AnnotatedElementUtils.isAnnotated(paramClass, ParameterObject.class))) {
boolean hasFlatAnnotation = p.hasParameterAnnotation(ParameterObject.class) || AnnotatedElementUtils.isAnnotated(paramClass, ParameterObject.class);
boolean hasNotFlatAnnotation = Arrays.stream(p.getParameterAnnotations())
.anyMatch(annotation -> Arrays.asList(RequestBody.class, RequestPart.class).contains(annotation.annotationType()));
if (!MethodParameterPojoExtractor.isSimpleType(paramClass)
&& (hasFlatAnnotation || (defaultFlatParamObject && !hasNotFlatAnnotation && !AbstractRequestService.isRequestTypeToIgnore(paramClass)))) {
MethodParameterPojoExtractor.extractFrom(paramClass).forEach(methodParameter -> {
optionalDelegatingMethodParameterCustomizer.ifPresent(customizer -> customizer.customize(p, methodParameter));
explodedParameters.add(methodParameter);
});
}
else if (defaultFlatParamObject) {
boolean isSimpleType = MethodParameterPojoExtractor.isSimpleType(paramClass);
List<Annotation> annotations = Arrays.stream(p.getParameterAnnotations())
.filter(annotation -> Arrays.asList(RequestBody.class, RequestPart.class).contains(annotation.annotationType()))
.toList();
boolean hasAnnotation = !annotations.isEmpty();
boolean shouldFlat = !isSimpleType && !hasAnnotation;
if (shouldFlat && !AbstractRequestService.isRequestTypeToIgnore(paramClass)) {
MethodParameterPojoExtractor.extractFrom(paramClass).forEach(methodParameter -> {
optionalDelegatingMethodParameterCustomizer
.ifPresent(customizer -> customizer.customize(p, methodParameter));
explodedParameters.add(methodParameter);
});
}
else {
String name = pNames != null ? pNames[i] : p.getParameterName();
explodedParameters.add(new DelegatingMethodParameter(p, name, null, false, false));
}
}
else {
String name = pNames != null ? pNames[i] : p.getParameterName();
explodedParameters.add(new DelegatingMethodParameter(p, name, null, false, false));
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
/*
*
* * Copyright 2019-2023 the original author or authors.
* *
* * Licensed under the Apache License, Version 2.0 (the "License");
* * you may not use this file except in compliance with the License.
* * You may obtain a copy of the License at
* *
* * https://www.apache.org/licenses/LICENSE-2.0
* *
* * Unless required by applicable law or agreed to in writing, software
* * distributed under the License is distributed on an "AS IS" BASIS,
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* * See the License for the specific language governing permissions and
* * limitations under the License.
*
*/

package test.org.springdoc.api.app171;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
* The type Hello controller.
*/
@RestController
public class HelloController {

/**
* PersonProjection interface.
*
* @return the PersonProjection
*/
@GetMapping(value = "/persons")
public PersonProjection persons() {
return new PersonDTO();
}

}
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
/*
*
* * Copyright 2019-2023 the original author or authors.
* *
* * Licensed under the Apache License, Version 2.0 (the "License");
* * you may not use this file except in compliance with the License.
* * You may obtain a copy of the License at
* *
* * https://www.apache.org/licenses/LICENSE-2.0
* *
* * Unless required by applicable law or agreed to in writing, software
* * distributed under the License is distributed on an "AS IS" BASIS,
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* * See the License for the specific language governing permissions and
* * limitations under the License.
*
*/

package test.org.springdoc.api.app171;

/**
* Simulate a dynamically generated class that implements the PersonProjection interface.
*/
public class PersonDTO implements PersonProjection {
private String email;

private String firstName;

private String lastName;

/**
* Instantiates a new Person dto.
*/
public PersonDTO() {
}

/**
* Instantiates a new Person dto.
*
* @param email the email
* @param firstName the first name
* @param lastName the last name
*/
public PersonDTO(final String email, final String firstName, final String lastName) {
this.email = email;
this.firstName = firstName;
this.lastName = lastName;
}

public String getEmail() {
return email;
}

public void setEmail(final String email) {
this.email = email;
}

public String getFirstName() {
return firstName;
}

public void setFirstName(final String firstName) {
this.firstName = firstName;
}

public String getLastName() {
return lastName;
}

public void setLastName(final String lastName) {
this.lastName = lastName;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
/*
*
* * Copyright 2019-2023 the original author or authors.
* *
* * Licensed under the Apache License, Version 2.0 (the "License");
* * you may not use this file except in compliance with the License.
* * You may obtain a copy of the License at
* *
* * https://www.apache.org/licenses/LICENSE-2.0
* *
* * Unless required by applicable law or agreed to in writing, software
* * distributed under the License is distributed on an "AS IS" BASIS,
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* * See the License for the specific language governing permissions and
* * limitations under the License.
*
*/

package test.org.springdoc.api.app171;

/**
* The type PersonProjection dto interface.
*/
public interface PersonProjection {
/**
* The Email.
*
*/
String getEmail();

/**
* The First name.
*
*/
String getFirstName();

/**
* The Last name.
*
*/
String getLastName();
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
/*
*
* * Copyright 2019-2023 the original author or authors.
* *
* * Licensed under the Apache License, Version 2.0 (the "License");
* * you may not use this file except in compliance with the License.
* * You may obtain a copy of the License at
* *
* * https://www.apache.org/licenses/LICENSE-2.0
* *
* * Unless required by applicable law or agreed to in writing, software
* * distributed under the License is distributed on an "AS IS" BASIS,
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* * See the License for the specific language governing permissions and
* * limitations under the License.
*
*/

package test.org.springdoc.api.app171;

import test.org.springdoc.api.AbstractSpringDocTest;

import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
* The type Spring doc app 193 test.
*/
public class SpringDocApp171Test extends AbstractSpringDocTest {

/**
* The type Spring doc test app.
*/
@SpringBootApplication
static class SpringDocTestApp {
}

}
Loading

0 comments on commit 74b2932

Please sign in to comment.