code review

Author: bnasslahsen

.gitignore

@@ -127,6 +127,7 @@ Desktop.ini
 *.*~
 *~
 .merge_file*
+.java-version
 
 ######################
 # Gradle Wrapper
@@ -141,4 +142,4 @@ Desktop.ini
 ######################
 # ESLint
 ######################
-.eslintcache
+.eslintcache

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

@@ -48,7 +48,6 @@
 
 import com.fasterxml.jackson.annotation.JsonView;
 import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
 import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator.Feature;
@@ -66,7 +65,6 @@
 import io.swagger.v3.oas.models.media.StringSchema;
 import io.swagger.v3.oas.models.parameters.Parameter;
 import io.swagger.v3.oas.models.responses.ApiResponses;
-import io.swagger.v3.oas.models.servers.Server;
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.slf4j.Logger;
@@ -85,6 +83,7 @@
 import org.springdoc.core.customizers.OpenApiCustomiser;
 import org.springdoc.core.customizers.OpenApiLocaleCustomizer;
 import org.springdoc.core.customizers.OperationCustomizer;
+import org.springdoc.core.customizers.RouterOperationCustomizer;
 import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.fn.AbstractRouterFunctionVisitor;
 import org.springdoc.core.fn.RouterFunctionData;
@@ -120,6 +119,7 @@
  * The type Abstract open api resource.
  * @author bnasslahsen
  * @author kevinraddatz
+ * @author hyeonisism
  */
 public abstract class AbstractOpenApiResource extends SpecFilter {
 
@@ -178,6 +178,11 @@ public abstract class AbstractOpenApiResource extends SpecFilter {
 	 */
 	private final Optional<List<OperationCustomizer>> operationCustomizers;
 
+	/**
+	 * The RouterOperation customizers.
+	 */
+	private final Optional<List<RouterOperationCustomizer>> routerOperationCustomizers;
+
 	/**
 	 * The method filters to use.
 	 */
@@ -217,6 +222,7 @@ public abstract class AbstractOpenApiResource extends SpecFilter {
 	 * @param operationParser the operation parser
 	 * @param operationCustomizers the operation customizers
 	 * @param openApiCustomisers the open api customisers
+	 * @param routerOperationCustomizers the router operation customisers
 	 * @param methodFilters the method filters
 	 * @param springDocConfigProperties the spring doc config properties
 	 * @param springDocProviders the spring doc providers
@@ -226,6 +232,7 @@ protected AbstractOpenApiResource(String groupName, ObjectFactory<OpenAPIService
 			GenericResponseService responseBuilder, OperationService operationParser,
 			Optional<List<OperationCustomizer>> operationCustomizers,
 			Optional<List<OpenApiCustomiser>> openApiCustomisers,
+			Optional<List<RouterOperationCustomizer>> routerOperationCustomizers,
 			Optional<List<OpenApiMethodFilter>> methodFilters,
 			SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
 		super();
@@ -236,6 +243,7 @@ protected AbstractOpenApiResource(String groupName, ObjectFactory<OpenAPIService
 		this.responseBuilder = responseBuilder;
 		this.operationParser = operationParser;
 		this.openApiCustomisers = openApiCustomisers;
+		this.routerOperationCustomizers = routerOperationCustomizers;
 		this.methodFilters = methodFilters;
 		this.springDocProviders = springDocProviders;
 		//add the default customizers
@@ -368,6 +376,9 @@ protected synchronized OpenAPI getOpenApi(Locale locale) {
 	 */
 	protected void calculatePath(HandlerMethod handlerMethod,
 			RouterOperation routerOperation, Locale locale, OpenAPI openAPI) {
+
+		routerOperation = customizeRouterOperation(routerOperation, handlerMethod);
+
 		String operationPath = routerOperation.getPath();
 		Set<RequestMethod> requestMethods = new HashSet<>(Arrays.asList(routerOperation.getMethods()));
 		io.swagger.v3.oas.annotations.Operation apiOperation = routerOperation.getOperation();
@@ -468,7 +479,7 @@ protected void calculatePath(HandlerMethod handlerMethod,
 			buildCallbacks(openAPI, methodAttributes, operation, apiCallbacks);
 
 			// allow for customisation
-			operation = customiseOperation(operation, handlerMethod);
+			operation = customizeOperation(operation, handlerMethod);
 
 			PathItem pathItemObject = buildPathItem(requestMethod, operation, operationPath, paths);
 			paths.addPathItem(operationPath, pathItemObject);
@@ -595,12 +606,15 @@ protected void calculatePath(RouterOperation routerOperation, Locale locale, Ope
 	 * @param consumes the consumes
 	 * @param produces the produces
 	 * @param headers the headers
+	 * @param params the params
 	 * @param locale the locale
 	 * @param openAPI the open api
 	 */
 	protected void calculatePath(HandlerMethod handlerMethod, String operationPath,
-			Set<RequestMethod> requestMethods, String[] consumes, String[] produces, String[] headers, Locale locale, OpenAPI openAPI) {
-		this.calculatePath(handlerMethod, new RouterOperation(operationPath, requestMethods.toArray(new RequestMethod[requestMethods.size()]), consumes, produces, headers), locale, openAPI);
+			Set<RequestMethod> requestMethods, String[] consumes, String[] produces, String[] headers, String[] params, Locale locale, OpenAPI openAPI) {
+		this.calculatePath(handlerMethod,
+				new RouterOperation(operationPath, requestMethods.toArray(new RequestMethod[requestMethods.size()]), consumes, produces, headers, params),
+				locale, openAPI);
 	}
 
 	/**
@@ -781,7 +795,6 @@ public static boolean containsResponseBody(HandlerMethod handlerMethod) {
 		return responseBodyAnnotation != null;
 	}
 
-
 	/**
 	 * Is rest controller boolean.
 	 *
@@ -827,7 +840,7 @@ protected Set<RequestMethod> getDefaultAllowedHttpMethods() {
 	 * @param handlerMethod the handler method
 	 * @return the operation
 	 */
-	protected Operation customiseOperation(Operation operation, HandlerMethod handlerMethod) {
+	protected Operation customizeOperation(Operation operation, HandlerMethod handlerMethod) {
 		if (operationCustomizers.isPresent()) {
 			List<OperationCustomizer> operationCustomizerList = operationCustomizers.get();
 			for (OperationCustomizer operationCustomizer : operationCustomizerList)
@@ -836,6 +849,22 @@ protected Operation customiseOperation(Operation operation, HandlerMethod handle
 		return operation;
 	}
 
+	/**
+	 * Customise router operation
+	 * @param routerOperation
+	 * @param handlerMethod
+	 * @return the router operation
+	 */
+	protected RouterOperation customizeRouterOperation(RouterOperation routerOperation, HandlerMethod handlerMethod) {
+		if (routerOperationCustomizers.isPresent()) {
+			List<RouterOperationCustomizer> routerOperationCustomizerList = routerOperationCustomizers.get();
+			for (RouterOperationCustomizer routerOperationCustomizer : routerOperationCustomizerList) {
+				routerOperation = routerOperationCustomizer.customize(routerOperation, handlerMethod);
+			}
+		}
+		return routerOperation;
+	}
+
 	/**
 	 * Merge routers.
 	 *

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

@@ -31,6 +31,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.springdoc.core.customizers.OpenApiCustomiser;
 import org.springdoc.core.customizers.OperationCustomizer;
+import org.springdoc.core.customizers.RouterOperationCustomizer;
 import org.springdoc.core.filters.OpenApiMethodFilter;
 
 import org.springframework.util.CollectionUtils;
@@ -58,6 +59,11 @@ public class GroupedOpenApi {
 	 */
 	private List<OperationCustomizer> operationCustomizers;
 
+	/**
+	 * The Router Operation customizers.
+	 */
+	private List<RouterOperationCustomizer> routerOperationCustomizers;
+
 	/**
 	 * The Paths to match.
 	 */
@@ -120,6 +126,7 @@ private GroupedOpenApi(Builder builder) {
 		this.displayName = StringUtils.defaultIfEmpty(builder.displayName, this.group);
 		this.openApiCustomisers = Objects.requireNonNull(builder.openApiCustomisers);
 		this.operationCustomizers = Objects.requireNonNull(builder.operationCustomizers);
+		this.routerOperationCustomizers = Objects.requireNonNull(builder.routerOperationCustomizers);
 		this.openApiMethodFilters = Objects.requireNonNull(builder.methodFilters);
 		if (CollectionUtils.isEmpty(this.pathsToMatch)
 				&& CollectionUtils.isEmpty(this.packagesToScan)
@@ -242,6 +249,15 @@ public List<OpenApiMethodFilter> getOpenApiMethodFilters() {
 		return openApiMethodFilters;
 	}
 
+	/**
+	 * Gets router operation customizers.
+	 *
+	 * @return the router operation customizers
+	 */
+	public List<RouterOperationCustomizer> getRouterOperationCustomizers() {
+		return routerOperationCustomizers;
+	}
+
 	/**
 	 * Gets display name.
 	 *
@@ -266,6 +282,11 @@ public static class Builder {
 		 */
 		private final List<OperationCustomizer> operationCustomizers = new ArrayList<>();
 
+		/**
+		 * The Router Operation customizers.
+		 */
+		private final List<RouterOperationCustomizer> routerOperationCustomizers = new ArrayList<>();
+
 		/**
 		 * The methods filters to apply.
 		 */
@@ -433,6 +454,17 @@ public Builder addOperationCustomizer(OperationCustomizer operationCustomizer) {
 			return this;
 		}
 
+		/**
+		 * Add router operation customizer builder
+		 *
+		 * @param routerOperationCustomizer the router operation customizer
+		 * @return the builder
+		 */
+		public Builder addRouterOperationCustomizer(RouterOperationCustomizer routerOperationCustomizer) {
+			this.routerOperationCustomizers.add(routerOperationCustomizer);
+			return this;
+		}
+
 		/**
 		 * Add method filter.
 		 *

springdoc-openapi-common/src/main/java/org/springdoc/core/annotations/RouterOperation.java

@@ -95,6 +95,14 @@
 	 */
 	String[] headers() default {};
 
+	/**
+	 * The parameters of the mapped request, narrowing the primary mapping.
+	 * Same format for any environment: a sequence of "myParam=myValue" style expressions,
+	 * with a request only mapped if each such parameter is found to have the given value.
+	 * @return the string [ ]
+	 */
+	String[] params() default {};
+
 	/**
 	 * The class of the Handler bean.
 	 * @return the class of the Bean

springdoc-openapi-common/src/main/java/org/springdoc/core/customizers/RouterOperationCustomizer.java

@@ -0,0 +1,25 @@
+package org.springdoc.core.customizers;
+
+import org.springdoc.core.fn.RouterOperation;
+
+import org.springframework.web.method.HandlerMethod;
+
+/**
+ * Implement and register a bean of type {@link RouterOperationCustomizer} to customize an router operation
+ * based on the handler method input on default OpenAPI descriptions but not groups
+ *
+ * @author hyeonisism
+ */
+@FunctionalInterface
+public interface RouterOperationCustomizer {
+
+	/**
+	 * Customize router operation.
+	 *
+	 * @param routerOperation input operation
+	 * @param handlerMethod original handler method
+	 * @return customized router operation
+	 */
+	RouterOperation customize(RouterOperation routerOperation, HandlerMethod handlerMethod);
+
+}

springdoc-openapi-common/src/main/java/org/springdoc/core/fn/RouterFunctionData.java

@@ -62,6 +62,11 @@ public class RouterFunctionData {
 	 */
 	private List<String> headers = new ArrayList<>();
 
+	/**
+	 * The Params.
+	 */
+	private List<String> params = new ArrayList<>();
+
 	/**
 	 * The Query params.
 	 */
@@ -93,6 +98,7 @@ public RouterFunctionData(String nestedOrPath, RouterFunctionData functionData)
 		this.consumes = Arrays.asList(functionData.getConsumes());
 		this.produces = Arrays.asList(functionData.getProduces());
 		this.headers = Arrays.asList(functionData.getHeaders());
+		this.params = Arrays.asList(functionData.getParams());
 		this.queryParams = functionData.getQueryParams();
 		this.methods = functionData.getMethods();
 		this.attributes = functionData.getAttributes();
@@ -181,6 +187,20 @@ public String[] getConsumes() {
 		return consumes.toArray(new String[consumes.size()]);
 	}
 
+	/**
+	 * Get params string [ ].
+	 *
+	 * @return the string [ ]
+	 */
+	public String[] getParams() { return params.toArray(new String[params.size()]); }
+
+	/**
+	 * Add params.
+	 *
+	 * @param params the params
+	 */
+	public void addParams(String params) { if(StringUtils.isNotBlank(params)) this.params.add(params); }
+
 	/**
 	 * Add consumes.
 	 *