Merge branch 'mc1arke-method-filtering'

Author: bnasslahsen

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

@@ -79,6 +79,7 @@
 import org.springdoc.core.GenericParameterService;
 import org.springdoc.core.GenericResponseService;
 import org.springdoc.core.MethodAttributes;
+import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.OpenAPIService;
 import org.springdoc.core.OperationService;
 import org.springdoc.core.SpringDocConfigProperties;
@@ -179,6 +180,11 @@ public abstract class AbstractOpenApiResource extends SpecFilter {
 	 */
 	private final Optional<List<OperationCustomizer>> operationCustomizers;
 
+	/**
+	 * The method filters to use.
+	 */
+	private final Optional<List<OpenApiMethodFilter>> methodFilters;
+
 	/**
 	 * The Ant path matcher.
 	 */
@@ -222,6 +228,7 @@ public abstract class AbstractOpenApiResource extends SpecFilter {
 	 * @param operationParser the operation parser
 	 * @param operationCustomizers the operation customizers
 	 * @param openApiCustomisers the open api customisers
+	 * @param methodFilters the method filters
 	 * @param springDocConfigProperties the spring doc config properties
 	 * @param springDocProviders the spring doc providers
 	 */
@@ -230,6 +237,7 @@ protected AbstractOpenApiResource(String groupName, ObjectFactory<OpenAPIService
 			GenericResponseService responseBuilder, OperationService operationParser,
 			Optional<List<OperationCustomizer>> operationCustomizers,
 			Optional<List<OpenApiCustomiser>> openApiCustomisers,
+			Optional<List<OpenApiMethodFilter>> methodFilters,
 			SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
 		super();
 		this.groupName = Objects.requireNonNull(groupName, "groupName");
@@ -239,6 +247,7 @@ protected AbstractOpenApiResource(String groupName, ObjectFactory<OpenAPIService
 		this.responseBuilder = responseBuilder;
 		this.operationParser = operationParser;
 		this.openApiCustomisers = openApiCustomisers;
+		this.methodFilters = methodFilters;
 		this.springDocProviders = springDocProviders;
 		//add the default customizers
 		Map<String, OpenApiCustomiser> existingOpenApiCustomisers = openAPIService.getContext().getBeansOfType(OpenApiCustomiser.class);
@@ -650,10 +659,24 @@ protected void getRouterFunctionPaths(String beanName, AbstractRouterFunctionVis
 	 * @return the boolean
 	 */
 	protected boolean isFilterCondition(HandlerMethod handlerMethod, String operationPath, String[] produces, String[] consumes, String[] headers) {
-		return isPackageToScan(handlerMethod.getBeanType().getPackage())
+		return isMethodToFilter(handlerMethod)
+				&& isPackageToScan(handlerMethod.getBeanType().getPackage())
 				&& isFilterCondition(operationPath, produces, consumes, headers);
 	}
 
+	/**
+	 * Is target method suitable for inclusion in current documentation/
+	 *
+	 * @param handlerMethod the method to check
+	 * @return whether the method should be included in the current OpenAPI definition
+	 */
+	protected boolean isMethodToFilter(HandlerMethod handlerMethod) {
+		return this.methodFilters
+				.map(Collection::stream)
+				.map(stream -> stream.allMatch(m -> m.isMethodToInclude(handlerMethod.getMethod())))
+				.orElse(true);
+	}
+
 	/**
 	 * Is condition to match boolean.
 	 *

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

@@ -27,6 +27,7 @@
 
 import org.springdoc.core.customizers.OpenApiCustomiser;
 import org.springdoc.core.customizers.OperationCustomizer;
+import org.springdoc.core.filters.OpenApiMethodFilter;
 
 import org.springframework.util.CollectionUtils;
 
@@ -88,6 +89,11 @@ public class GroupedOpenApi {
 	 */
 	private final List<String> consumesToMatch;
 
+	/**
+	 * The method filters to use.
+	 */
+	private final List<OpenApiMethodFilter> openApiMethodFilters;
+
 	/**
 	 * Instantiates a new Grouped open api.
 	 *
@@ -104,6 +110,7 @@ private GroupedOpenApi(Builder builder) {
 		this.pathsToExclude = builder.pathsToExclude;
 		this.openApiCustomisers = Objects.requireNonNull(builder.openApiCustomisers);
 		this.operationCustomizers = Objects.requireNonNull(builder.operationCustomizers);
+		this.openApiMethodFilters = Objects.requireNonNull(builder.methodFilters);
 		if (CollectionUtils.isEmpty(this.pathsToMatch)
 				&& CollectionUtils.isEmpty(this.packagesToScan)
 				&& CollectionUtils.isEmpty(this.producesToMatch)
@@ -112,7 +119,8 @@ private GroupedOpenApi(Builder builder) {
 				&& CollectionUtils.isEmpty(this.pathsToExclude)
 				&& CollectionUtils.isEmpty(this.packagesToExclude)
 				&& CollectionUtils.isEmpty(openApiCustomisers)
-				&& CollectionUtils.isEmpty(operationCustomizers))
+				&& CollectionUtils.isEmpty(operationCustomizers)
+				&& CollectionUtils.isEmpty(openApiMethodFilters))
 			throw new IllegalStateException("Packages to scan or paths to filter or openApiCustomisers/operationCustomizers can not be all null for the group:" + this.group);
 	}
 
@@ -215,6 +223,15 @@ public List<OperationCustomizer> getOperationCustomizers() {
 		return operationCustomizers;
 	}
 
+	/**
+	 * Gets open api method filters.
+	 *
+	 * @return the open api method filters
+	 */
+	public List<OpenApiMethodFilter> getOpenApiMethodFilters() {
+		return openApiMethodFilters;
+	}
+
 	/**
 	 * The type Builder.
 	 * @author bnasslahsen
@@ -230,6 +247,11 @@ public static class Builder {
 		 */
 		private final List<OperationCustomizer> operationCustomizers = new ArrayList<>();
 
+		/**
+		 * The methods filters to apply.
+		 */
+		private final List<OpenApiMethodFilter> methodFilters = new ArrayList<>();
+
 		/**
 		 * The Group.
 		 */
@@ -387,6 +409,17 @@ public Builder addOperationCustomizer(OperationCustomizer operationCustomizer) {
 			return this;
 		}
 
+		/**
+		 * Add method filter.
+		 *
+		 * @param methodFilter an additional filter to apply to the matched methods
+		 * @return the builder
+		 */
+		public Builder addOpenApiMethodFilter(OpenApiMethodFilter methodFilter) {
+			this.methodFilters.add(methodFilter);
+			return this;
+		}
+
 		/**
 		 * Build grouped open api.
 		 *

springdoc-openapi-common/src/main/java/org/springdoc/core/filters/OpenApiMethodFilter.java

@@ -0,0 +1,44 @@
+/*
+ *
+ *  *
+ *  *  * Copyright 2019-2020 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 org.springdoc.core.filters;
+
+import java.lang.reflect.Method;
+
+/**
+ * A filter to allow conditionally including any detected methods in an OpenApi definition.
+ * @author michael.clarke
+ */
+@FunctionalInterface
+public interface OpenApiMethodFilter {
+
+	/**
+	 * Whether the given method should be included in the generated OpenApi definitions. Only methods from classes
+	 * detected by the relevant loader will be passed to this filter; it cannot be used to load methods that are not
+	 * annotated with `RequestMethod` or similar mechanisms. Methods that are rejected by this filter will not be
+	 * processed any further, although methods accepted by this filter may still be rejected by other checks, such as
+	 * package inclusion checks so may still be excluded from the final OpenApi definition.
+	 *
+	 * @param method the method to perform checks against
+	 * @return whether this method should be used for further processing
+	 */
+	boolean isMethodToInclude(Method method);
+
+}

springdoc-openapi-common/src/test/java/org/springdoc/api/AbstractOpenApiResourceTest.java

@@ -43,6 +43,7 @@
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springdoc.core.AbstractRequestService;
 import org.springdoc.core.GenericResponseService;
+import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.OpenAPIService;
 import org.springdoc.core.OperationService;
 import org.springdoc.core.SpringDocConfigProperties;
@@ -127,6 +128,7 @@ void calculatePathFromRouterOperation() {
 				operationParser,
 				Optional.empty(),
 				Optional.empty(),
+				Optional.empty(),
 				new SpringDocConfigProperties(),
 				springDocProviders
 		);
@@ -197,6 +199,7 @@ void preLoadingModeShouldNotOverwriteServers() throws InterruptedException {
 				operationParser,
 				Optional.empty(),
 				Optional.of(singletonList(openApiCustomiser)),
+				Optional.empty(),
 				properties, springDocProviders
 		);
 
@@ -215,8 +218,8 @@ void preLoadingModeShouldNotOverwriteServers() throws InterruptedException {
 
 	private static class EmptyPathsOpenApiResource extends AbstractOpenApiResource {
 
-		EmptyPathsOpenApiResource(String groupName, ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
-			super(groupName, openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, springDocConfigProperties, springDocProviders);
+		EmptyPathsOpenApiResource(String groupName, ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, Optional<List<OpenApiMethodFilter>> methodFilters, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
+			super(groupName, openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, methodFilters, springDocConfigProperties, springDocProviders);
 		}
 
 		@Override

springdoc-openapi-javadoc/src/test/java/test/org/springdoc/api/app94/SpringDocApp94Test.java

@@ -29,6 +29,7 @@
 import org.apache.commons.lang3.RandomStringUtils;
 import org.springdoc.core.AbstractRequestService;
 import org.springdoc.core.GenericResponseService;
+import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.OpenAPIService;
 import org.springdoc.core.OperationService;
 import org.springdoc.core.SpringDocConfigProperties;
@@ -117,22 +118,24 @@ public RequestMappingHandlerMapping defaultTestHandlerMapping(GreetingController
 		/**
 		 * Open api resource open api web mvc resource.
 		 *
-		 * @param openAPIBuilderObjectFactory the open api builder object factory 
-		 * @param requestBuilder the request builder 
-		 * @param responseBuilder the response builder 
-		 * @param operationParser the operation parser 
-		 * @param operationCustomizers the operation customizers 
+		 * @param openAPIBuilderObjectFactory the open api builder object factory
+		 * @param requestBuilder the request builder
+		 * @param responseBuilder the response builder
+		 * @param operationParser the operation parser
+		 * @param operationCustomizers the operation customizers
 		 * @param springDocConfigProperties the spring doc config properties
-		 * @param openApiCustomisers the open api customisers 
+		 * @param openApiCustomisers the open api customisers
+		 * @param methodFilters the method filters
+		 * @param springDocProviders the spring doc providers
 		 * @return the open api web mvc resource
 		 */
 		@Bean(name = "openApiResource")
 		public OpenApiWebMvcResource openApiResource(ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder,
 				OperationService operationParser,Optional<List<OperationCustomizer>> operationCustomizers,
 				SpringDocConfigProperties springDocConfigProperties,
-				Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocProviders springDocProviders) {
+				Optional<List<OpenApiCustomiser>> openApiCustomisers, Optional<List<OpenApiMethodFilter>> methodFilters,SpringDocProviders springDocProviders) {
 			return new OpenApiWebMvcResource(DEFAULT_GROUP_NAME, openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser,
-					operationCustomizers, openApiCustomisers, springDocConfigProperties, springDocProviders);
+					operationCustomizers, openApiCustomisers,methodFilters, springDocConfigProperties, springDocProviders);
 		}
 
 		/**

springdoc-openapi-webflux-core/src/main/java/org/springdoc/webflux/api/MultipleOpenApiResource.java

@@ -132,15 +132,16 @@ public void afterPropertiesSet() {
 	private OpenApiResource buildWebFluxOpenApiResource(GroupedOpenApi item) {
 		if (!springDocConfigProperties.isUseManagementPort() && !ACTUATOR_DEFAULT_GROUP.equals(item.getGroup()))
 			return new OpenApiWebfluxResource(item.getGroup(),
-				defaultOpenAPIBuilder,
-				requestBuilder,
-				responseBuilder,
-				operationParser,
-				Optional.of(item.getOperationCustomizers()),
-				Optional.of(item.getOpenApiCustomisers()),
-				springDocConfigProperties,
-				springDocProviders
-		);
+					defaultOpenAPIBuilder,
+					requestBuilder,
+					responseBuilder,
+					operationParser,
+					Optional.of(item.getOperationCustomizers()),
+					Optional.of(item.getOpenApiCustomisers()),
+					Optional.of(item.getOpenApiMethodFilters()),
+					springDocConfigProperties,
+					springDocProviders
+			);
 		else
 			return new OpenApiActuatorResource(item.getGroup(),
 					defaultOpenAPIBuilder,
@@ -149,6 +150,7 @@ private OpenApiResource buildWebFluxOpenApiResource(GroupedOpenApi item) {
 					operationParser,
 					Optional.of(item.getOperationCustomizers()),
 					Optional.of(item.getOpenApiCustomisers()),
+					Optional.of(item.getOpenApiMethodFilters()),
 					springDocConfigProperties,
 					springDocProviders);
 	}

springdoc-openapi-webflux-core/src/main/java/org/springdoc/webflux/api/OpenApiActuatorResource.java

@@ -29,6 +29,7 @@
 import io.swagger.v3.oas.annotations.Operation;
 import org.springdoc.core.AbstractRequestService;
 import org.springdoc.core.GenericResponseService;
+import org.springdoc.core.filters.OpenApiMethodFilter;
 import org.springdoc.core.OpenAPIService;
 import org.springdoc.core.OperationService;
 import org.springdoc.core.SpringDocConfigProperties;
@@ -67,10 +68,12 @@ public class OpenApiActuatorResource extends OpenApiResource {
 	 * @param operationParser the operation parser
 	 * @param operationCustomizers the operation customizers
 	 * @param openApiCustomisers the open api customisers
+	 * @param methodFilters the method filters
 	 * @param springDocConfigProperties the spring doc config properties
+	 * @param springDocProviders the spring doc providers
 	 */
-	public OpenApiActuatorResource(String groupName, ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
-		super(groupName, openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, springDocConfigProperties, springDocProviders);
+	public OpenApiActuatorResource(String groupName, ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, Optional<List<OpenApiMethodFilter>> methodFilters, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
+		super(groupName, openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, methodFilters, springDocConfigProperties, springDocProviders);
 	}
 
 	/**
@@ -82,10 +85,12 @@ public OpenApiActuatorResource(String groupName, ObjectFactory<OpenAPIService> o
 	 * @param operationParser the operation parser
 	 * @param operationCustomizers the operation customizers
 	 * @param openApiCustomisers the open api customisers
+	 * @param methodFilters the method filters
 	 * @param springDocConfigProperties the spring doc config properties
+	 * @param springDocProviders the spring doc providers
 	 */
-	public OpenApiActuatorResource(ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
-		super(openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, springDocConfigProperties, springDocProviders);
+	public OpenApiActuatorResource(ObjectFactory<OpenAPIService> openAPIBuilderObjectFactory, AbstractRequestService requestBuilder, GenericResponseService responseBuilder, OperationService operationParser, Optional<List<OperationCustomizer>> operationCustomizers, Optional<List<OpenApiCustomiser>> openApiCustomisers, Optional<List<OpenApiMethodFilter>> methodFilters, SpringDocConfigProperties springDocConfigProperties, SpringDocProviders springDocProviders) {
+		super(openAPIBuilderObjectFactory, requestBuilder, responseBuilder, operationParser, operationCustomizers, openApiCustomisers, methodFilters, springDocConfigProperties, springDocProviders);
 	}
 
 	/**