Merge branch 'gebezs-javadoc-enhancement'

Author: bnasslahsen

springdoc-openapi-common/src/main/java/org/springdoc/api/AbstractOpenApiResource.java

@@ -315,7 +315,7 @@ protected synchronized OpenAPI getOpenApi(Locale locale) {
 			Map<String, Object> findControllerAdvice = openAPIService.getControllerAdviceMap();
 			// calculate generic responses
 			openApi = openAPIService.getCalculatedOpenAPI();
-			if (springDocConfigProperties.isOverrideWithGenericResponse()) {
+			if (springDocConfigProperties.isDefaultOverrideWithGenericResponse()) {
 				if (!CollectionUtils.isEmpty(mappingsMap))
 					findControllerAdvice.putAll(mappingsMap);
 				responseBuilder.buildGenericResponse(openApi.getComponents(), findControllerAdvice, finalLocale);
@@ -463,8 +463,18 @@ protected void calculatePath(HandlerMethod handlerMethod, RouterOperation router
 			// get javadoc method description
 			if (javadocProvider != null) {
 				String description = javadocProvider.getMethodJavadocDescription(handlerMethod.getMethod());
-				if (!StringUtils.isEmpty(description) && StringUtils.isEmpty(operation.getDescription()))
+				String summary = javadocProvider.getFirstSentence(description);
+				boolean emptyOverrideDescription = StringUtils.isEmpty(operation.getDescription());
+				boolean emptyOverrideSummary = StringUtils.isEmpty(operation.getSummary());
+				if (!StringUtils.isEmpty(description) && emptyOverrideDescription) {
 					operation.setDescription(description);
+				}
+				// if there is a previously set description
+				// but no summary then it is intentional
+				// we keep it as is
+				if (!StringUtils.isEmpty(summary) && emptyOverrideSummary && emptyOverrideDescription) {
+					operation.setSummary(javadocProvider.getFirstSentence(description));
+				}
 			}
 
 			Set<io.swagger.v3.oas.annotations.callbacks.Callback> apiCallbacks = AnnotatedElementUtils.findMergedRepeatableAnnotations(method, io.swagger.v3.oas.annotations.callbacks.Callback.class);

springdoc-openapi-common/src/main/java/org/springdoc/core/GenericResponseService.java

@@ -22,10 +22,12 @@
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -62,6 +64,7 @@
 import org.springframework.web.method.ControllerAdviceBean;
 import org.springframework.web.method.HandlerMethod;
 
+import static java.util.Arrays.asList;
 import static org.springdoc.core.Constants.DEFAULT_DESCRIPTION;
 import static org.springdoc.core.SpringDocAnnotationsUtils.extractSchema;
 import static org.springdoc.core.SpringDocAnnotationsUtils.getContent;
@@ -73,6 +76,11 @@
  * @author bnasslahsen
  */
 public class GenericResponseService {
+	/**
+	 * This extension name is used to temporary store
+	 * the exception classes.
+	 */
+	private static final String EXTENSION_EXCEPTION_CLASSES = "x-exception-class";
 
 	/**
 	 * The Operation builder.
@@ -133,7 +141,11 @@ public GenericResponseService(OperationService operationService, List<ReturnType
 	 */
 	public ApiResponses build(Components components, HandlerMethod handlerMethod, Operation operation,
 			MethodAttributes methodAttributes) {
-		ApiResponses apiResponses = methodAttributes.calculateGenericMapResponse(getGenericMapResponse(handlerMethod.getBeanType()));
+		Map<String, ApiResponse> genericMapResponse = getGenericMapResponse(handlerMethod.getBeanType());
+		if (springDocConfigProperties.isOverrideWithGenericResponse()) {
+			genericMapResponse = filterAndEnrichGenericMapResponseByDeclarations(handlerMethod, genericMapResponse);
+		}
+		ApiResponses apiResponses = methodAttributes.calculateGenericMapResponse(genericMapResponse);
 		//Then use the apiResponses from documentation
 		ApiResponses apiResponsesFromDoc = operation.getResponses();
 		if (!CollectionUtils.isEmpty(apiResponsesFromDoc))
@@ -145,6 +157,41 @@ public ApiResponses build(Components components, HandlerMethod handlerMethod, Op
 		return apiResponses;
 	}
 
+	/**
+	 * Filters the generic API responses by the declared exceptions.
+	 * If Javadoc comment found for the declaration than it overrides the default description.
+	 *
+	 * @param handlerMethod the method which can have exception declarations
+	 * @param genericMapResponse the default generic API responses
+	 * @return the filtered and enriched responses
+	 */
+	private Map<String, ApiResponse> filterAndEnrichGenericMapResponseByDeclarations(HandlerMethod handlerMethod, Map<String, ApiResponse> genericMapResponse) {
+		Map<String, ApiResponse> result = new HashMap<>();
+		for (Map.Entry<String, ApiResponse> genericResponse : genericMapResponse.entrySet()) {
+			Map<String, Object> extensions = genericResponse.getValue().getExtensions();
+			Set<Class<?>> genericExceptions = (Set<Class<?>>) extensions.get(EXTENSION_EXCEPTION_CLASSES);
+			for (Class<?> declaredException : handlerMethod.getMethod().getExceptionTypes()) {
+				if (genericExceptions.contains(declaredException)) {
+					ApiResponse clone = cloneApiResponse(genericResponse.getValue());
+					clone.getExtensions().remove(EXTENSION_EXCEPTION_CLASSES);
+					if (operationService.getJavadocProvider() != null) {
+						JavadocProvider javadocProvider = operationService.getJavadocProvider();
+						Map<String, String> javadocThrows = javadocProvider.getMethodJavadocThrows(handlerMethod.getMethod());
+						String description = javadocThrows.get(declaredException.getName());
+						if (description == null) {
+							description = javadocThrows.get(declaredException.getSimpleName());
+						}
+						if (description != null && !description.trim().isEmpty()) {
+							clone.setDescription(description);
+						}
+					}
+					result.put(genericResponse.getKey(), clone);
+				}
+			}
+		}
+		return result;
+	}
+
 	/**
 	 * Build generic response.
 	 *
@@ -502,6 +549,23 @@ else if (CollectionUtils.isEmpty(apiResponse.getContent()))
 			if (schemaN != null && ArrayUtils.isNotEmpty(methodAttributes.getMethodProduces()))
 				Arrays.stream(methodAttributes.getMethodProduces()).forEach(mediaTypeStr -> mergeSchema(existingContent, schemaN, mediaTypeStr));
 		}
+		if (springDocConfigProperties.isOverrideWithGenericResponse()
+				&& methodParameter.getExecutable().isAnnotationPresent(ExceptionHandler.class)) {
+			// ExceptionHandler's exception class resolution is non-trivial
+			// more info on its javadoc
+			ExceptionHandler exceptionHandler = methodParameter.getExecutable().getAnnotation(ExceptionHandler.class);
+			Set<Class<?>> exceptions = new HashSet<>();
+			if (exceptionHandler.value().length == 0) {
+				for (Parameter parameter : methodParameter.getExecutable().getParameters()) {
+					if (Throwable.class.isAssignableFrom(parameter.getType())) {
+						exceptions.add(parameter.getType());
+					}
+				}
+			} else {
+				exceptions.addAll(asList(exceptionHandler.value()));
+			}
+			apiResponse.addExtension(EXTENSION_EXCEPTION_CLASSES, exceptions);
+		}
 		apiResponsesOp.addApiResponse(httpCode, apiResponse);
 	}
 
@@ -620,4 +684,15 @@ private boolean isHttpCodePresent(String httpCode, Set<io.swagger.v3.oas.annotat
 	public static void setResponseEntityExceptionHandlerClass(Class<?> responseEntityExceptionHandlerClass) {
 		GenericResponseService.responseEntityExceptionHandlerClass = responseEntityExceptionHandlerClass;
 	}
+
+	private ApiResponse cloneApiResponse(ApiResponse original) {
+		ApiResponse clone = new ApiResponse();
+		clone.set$ref(original.get$ref());
+		clone.setDescription(original.getDescription());
+		clone.setContent(original.getContent());
+		clone.setHeaders(original.getHeaders() == null ? null : new HashMap<>(original.getHeaders()));
+		clone.setExtensions(original.getExtensions() == null ? null : new HashMap<>(original.getExtensions()));
+		clone.setLinks(original.getLinks() == null ? null : new HashMap<>(original.getLinks()));
+		return clone;
+	}
 }

springdoc-openapi-common/src/main/java/org/springdoc/core/OpenAPIService.java

@@ -57,6 +57,7 @@
 import org.slf4j.LoggerFactory;
 import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
 import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
+import org.springdoc.core.providers.JavadocProvider;
 
 import org.springframework.beans.BeansException;
 import org.springframework.beans.factory.config.BeanDefinition;
@@ -155,6 +156,11 @@ public class OpenAPIService implements ApplicationContextAware {
 	 */
 	private PropertyResolverUtils propertyResolverUtils;
 
+	/**
+	 * The javadoc provider.
+	 */
+	private Optional<JavadocProvider> javadocProvider;
+
 	/**
 	 * The Basic error controller.
 	 */
@@ -189,7 +195,8 @@ public class OpenAPIService implements ApplicationContextAware {
 	public OpenAPIService(Optional<OpenAPI> openAPI, SecurityService securityParser,
 			SpringDocConfigProperties springDocConfigProperties, PropertyResolverUtils propertyResolverUtils,
 			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
-			Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers) {
+			Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
+			Optional<JavadocProvider> javadocProvider) {
 		if (openAPI.isPresent()) {
 			this.openAPI = openAPI.get();
 			if (this.openAPI.getComponents() == null)
@@ -204,6 +211,7 @@ public OpenAPIService(Optional<OpenAPI> openAPI, SecurityService securityParser,
 		this.springDocConfigProperties = springDocConfigProperties;
 		this.openApiBuilderCustomisers = openApiBuilderCustomizers;
 		this.serverBaseUrlCustomizers = serverBaseUrlCustomizers;
+		this.javadocProvider = javadocProvider;
 		if (springDocConfigProperties.isUseFqn())
 			TypeNameResolver.std.setUseFqn(true);
 	}
@@ -348,8 +356,21 @@ public Operation buildTags(HandlerMethod handlerMethod, Operation operation, Ope
 			}
 		}
 
-		if (isAutoTagClasses(operation))
-			operation.addTagsItem(splitCamelCase(handlerMethod.getBeanType().getSimpleName()));
+		if (isAutoTagClasses(operation)) {
+			String tagAutoName = splitCamelCase(handlerMethod.getBeanType().getSimpleName());
+			operation.addTagsItem(tagAutoName);
+			if (javadocProvider.isPresent()) {
+				String description = javadocProvider.get().getClassJavadoc(handlerMethod.getBeanType());
+				if (StringUtils.isNotBlank(description)) {
+					io.swagger.v3.oas.models.tags.Tag tag = new io.swagger.v3.oas.models.tags.Tag();
+					tag.setName(tagAutoName);
+					tag.setDescription(description);
+					if (openAPI.getTags() == null || !openAPI.getTags().contains(tag)) {
+						openAPI.addTagsItem(tag);
+					}
+				}
+			}
+		}
 
 		if (!CollectionUtils.isEmpty(tags)) {
 			// Existing tags
@@ -733,7 +754,7 @@ public SecurityService getSecurityParser() {
 
 	/**
 	 * Gets server base URL
-	 * 
+	 *
 	 * @return the server base URL
 	 */
 	public String getServerBaseUrl() {

springdoc-openapi-common/src/main/java/org/springdoc/core/SpringDocConfigProperties.java

@@ -115,7 +115,7 @@ public class SpringDocConfigProperties {
 	/**
 	 * The Override with generic response.
 	 */
-	private boolean overrideWithGenericResponse = true;
+	private Boolean overrideWithGenericResponse;
 
 	/**
 	 * The Remove broken reference definitions.
@@ -579,16 +579,28 @@ public void setDefaultProducesMediaType(String defaultProducesMediaType) {
 	 *
 	 * @return the boolean
 	 */
-	public boolean isOverrideWithGenericResponse() {
-		return overrideWithGenericResponse;
+	public Boolean isOverrideWithGenericResponse() {
+		return overrideWithGenericResponse != null && overrideWithGenericResponse;
+	}
+
+	/**
+	 * Gets default override with generic response.
+	 *
+	 * @return the default override with generic response
+	 */
+	public boolean isDefaultOverrideWithGenericResponse() {
+		if (overrideWithGenericResponse == null)
+			return true;
+		else
+			return overrideWithGenericResponse;
 	}
 
 	/**
 	 * Sets override with generic response.
 	 *
 	 * @param overrideWithGenericResponse the override with generic response
 	 */
-	public void setOverrideWithGenericResponse(boolean overrideWithGenericResponse) {
+	public void setOverrideWithGenericResponse(Boolean overrideWithGenericResponse) {
 		this.overrideWithGenericResponse = overrideWithGenericResponse;
 	}
 

springdoc-openapi-common/src/main/java/org/springdoc/core/SpringDocConfiguration.java

@@ -228,8 +228,8 @@ OpenAPIService openAPIBuilder(Optional<OpenAPI> openAPI,
 			SecurityService securityParser,
 			SpringDocConfigProperties springDocConfigProperties,PropertyResolverUtils propertyResolverUtils,
 			Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers,
-			Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers) {
-		return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers, serverBaseUrlCustomisers);
+			Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers, Optional<JavadocProvider> javadocProvider) {
+		return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers, serverBaseUrlCustomisers, javadocProvider);
 	}
 
 	/**

springdoc-openapi-common/src/main/java/org/springdoc/core/providers/JavadocProvider.java

@@ -22,13 +22,22 @@
 
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
+import java.util.Map;
 
 /**
  * The interface Javadoc provider.
  * @author bnasslashen
  */
 public interface JavadocProvider {
 
+	/**
+	 * Gets class description.
+	 *
+	 * @param cl the class
+	 * @return the class description
+	 */
+	String getClassJavadoc(Class<?> cl);
+
 	/**
 	 * Gets method description.
 	 *
@@ -45,6 +54,14 @@ public interface JavadocProvider {
 	 */
 	String getMethodJavadocReturn(Method method);
 
+	/**
+	 * Gets method throws declaration.
+	 *
+	 * @param method the method
+	 * @return the method throws (name-description map)
+	 */
+	Map<String, String> getMethodJavadocThrows(Method method);
+
 	/**
 	 * Gets param javadoc.
 	 *
@@ -55,5 +72,12 @@ public interface JavadocProvider {
 	String getParamJavadoc(Method method, String name);
 
 	String getFieldJavadoc(Field field);
+
+	/**
+	 * Returns the first sentence of a javadoc comment.
+	 * @param text the javadoc comment's text
+	 * @return the first sentence based on javadoc guidelines
+	 */
+	String getFirstSentence(String text);
 }
 

springdoc-openapi-javadoc/src/main/java/org/springdoc/openapi/javadoc/JavadocPropertyCustomizer.java

@@ -76,12 +76,12 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 				if (!CollectionUtils.isEmpty(fields)) {
 					if (!type.isSchemaProperty()) {
 						Schema existingSchema = context.resolve(type);
-						setJavadocDescription(fields, existingSchema);
+						setJavadocDescription(cls, fields, 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(fields, existingSchema);
+						setJavadocDescription(cls, fields, existingSchema);
 					}
 				}
 				return resolvedSchema;
@@ -96,8 +96,11 @@ else if (resolvedSchema != null && resolvedSchema.get$ref() != null && resolvedS
 	 * @param fields the fields
 	 * @param existingSchema the existing schema
 	 */
-	private void setJavadocDescription(List<Field> fields, Schema existingSchema) {
+	private void setJavadocDescription(Class<?> cls, List<Field> fields, Schema existingSchema) {
 		if (existingSchema != null) {
+			if (StringUtils.isBlank(existingSchema.getDescription())) {
+				existingSchema.setDescription(javadocProvider.getClassJavadoc(cls));
+			}
 			Map<String, Schema> properties = existingSchema.getProperties();
 			if (!CollectionUtils.isEmpty(properties))
 				properties.entrySet().stream()