Allow excluding individual methods from OpenApi output

It is currently possible to prevent methods from being included in the
OpenAPI output by ensuring the parent class is not covered by the
`packagesToScan` or `pathsToMatch` configuration, but where a method
that a user doesn't want included in the output is present in a class
that is included in the configuration, and that method shares a path
with other endpoints that also require inclusion, there's no way for a
user to exclude the method from being exposed as an operation in the
OpenAPI output.

To overcome this limitation, a MethodFilter has been introduced which
allows for a user to selectively exclude individual methods from being
parsed for their definitions. Every method that's detected for
potential inclusion in the OpenApi output is passed to the filter, and
any method that the filter rejects is excluded from further processing.
As multiple filters can be applied in a single configuration, the
result of all the filters is combined in an 'and' result, so all
filters must accept a method the have it available in the output.

This functionality allows for the annotation filtering feature in
SpringFox to be re-implemented by users, by creating a method filter
similar to `method -> method.isAnnotationPresent(MyAnnotation.class)`,
although allows much finer control since any other reflective
attributes of the method can also be checked at the same time.

Author: mc1arke

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

@@ -650,10 +650,27 @@ 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 isSuitableTargetMethod(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 isSuitableTargetMethod(HandlerMethod handlerMethod) {
+		return springDocConfigProperties.getGroupConfigs().stream()
+			.filter(groupConfig -> this.groupName.equals(groupConfig.getGroup()))
+			.findAny()
+			.map(GroupConfig::getMethodFilters)
+			.map(Collection::stream)
+			.map(stream -> stream.allMatch(m -> m.includeMethodInOpenApi(handlerMethod.getMethod())))
+			.orElse(true);
+    }
+
 	/**
 	 * Is condition to match boolean.
 	 *

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

@@ -88,6 +88,11 @@ public class GroupedOpenApi {
 	 */
 	private final List<String> consumesToMatch;
 
+	/**
+	 * The method filters to use.
+	 */
+	private final List<MethodFilter> methodFilters;
+
 	/**
 	 * Instantiates a new Grouped open api.
 	 *
@@ -104,6 +109,7 @@ private GroupedOpenApi(Builder builder) {
 		this.pathsToExclude = builder.pathsToExclude;
 		this.openApiCustomisers = Objects.requireNonNull(builder.openApiCustomisers);
 		this.operationCustomizers = Objects.requireNonNull(builder.operationCustomizers);
+		this.methodFilters = Objects.requireNonNull(builder.methodFilters);
 		if (CollectionUtils.isEmpty(this.pathsToMatch)
 				&& CollectionUtils.isEmpty(this.packagesToScan)
 				&& CollectionUtils.isEmpty(this.producesToMatch)
@@ -112,7 +118,8 @@ private GroupedOpenApi(Builder builder) {
 				&& CollectionUtils.isEmpty(this.pathsToExclude)
 				&& CollectionUtils.isEmpty(this.packagesToExclude)
 				&& CollectionUtils.isEmpty(openApiCustomisers)
-				&& CollectionUtils.isEmpty(operationCustomizers))
+				&& CollectionUtils.isEmpty(operationCustomizers)
+				&& CollectionUtils.isEmpty(methodFilters))
 			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 +222,15 @@ public List<OperationCustomizer> getOperationCustomizers() {
 		return operationCustomizers;
 	}
 
+	/**
+	 * Gets method filters.
+	 *
+	 * @return the method filters
+	 */
+	public List<MethodFilter> getMethodFilters() {
+		return methodFilters;
+	}
+
 	/**
 	 * The type Builder.
 	 * @author bnasslahsen
@@ -230,6 +246,11 @@ public static class Builder {
 		 */
 		private final List<OperationCustomizer> operationCustomizers = new ArrayList<>();
 
+		/**
+		 * The methods filters to apply.
+		 */
+		private final List<MethodFilter> methodFilters = new ArrayList<>();
+
 		/**
 		 * The Group.
 		 */
@@ -387,6 +408,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 addMethodFilter(MethodFilter methodFilter) {
+			this.methodFilters.add(methodFilter);
+			return this;
+		}
+
 		/**
 		 * Build grouped open api.
 		 *

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

@@ -0,0 +1,43 @@
+/*
+ *
+ *  *
+ *  *  * 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;
+
+import java.lang.reflect.Method;
+
+/**
+ * A filter to allow conditionally including any detected methods in an OpenApi definition.
+ * @author michael.clarke
+ */
+@FunctionalInterface
+public interface MethodFilter {
+
+	/**
+	 * 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 includeMethodInOpenApi(Method method);
+}

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

@@ -1081,6 +1081,11 @@ public static class GroupConfig {
 		 */
 		private List<String> consumesToMatch;
 
+		/**
+		 * The method filters to use.
+		 */
+		private List<MethodFilter> methodFilters;
+
 		/**
 		 * Instantiates a new Group config.
 		 */
@@ -1098,10 +1103,32 @@ public GroupConfig() {
 		 * @param producesToMatch the produces to match
 		 * @param consumesToMatch the consumes to match
 		 * @param headersToMatch the headers to match
+		 * @deprecated Use {@link #GroupConfig(String, List, List, List, List, List, List, List, List)}
 		 */
+		@Deprecated
 		public GroupConfig(String group, List<String> pathsToMatch, List<String> packagesToScan,
 				List<String> packagesToExclude, List<String> pathsToExclude,
-				List<String> producesToMatch,List<String> consumesToMatch,List<String> headersToMatch) {
+				List<String> producesToMatch, List<String> consumesToMatch, List<String> headersToMatch) {
+			this(group, pathsToMatch, packagesToScan, packagesToExclude, pathsToExclude, producesToMatch, consumesToMatch, headersToMatch, new ArrayList<>());
+		}
+
+		/**
+		 * Instantiates a new Group config.
+		 *
+		 * @param group             the group
+		 * @param pathsToMatch      the paths to match
+		 * @param packagesToScan    the packages to scan
+		 * @param packagesToExclude the packages to exclude
+		 * @param pathsToExclude    the paths to exclude
+		 * @param producesToMatch   the produces to match
+		 * @param consumesToMatch   the consumes to match
+		 * @param headersToMatch    the headers to match
+		 * @param methodFilters     the method filters to use
+		 */
+		public GroupConfig(String group, List<String> pathsToMatch, List<String> packagesToScan,
+						   List<String> packagesToExclude, List<String> pathsToExclude,
+						   List<String> producesToMatch, List<String> consumesToMatch, List<String> headersToMatch,
+						   List<MethodFilter> methodFilters) {
 			this.pathsToMatch = pathsToMatch;
 			this.pathsToExclude = pathsToExclude;
 			this.packagesToExclude = packagesToExclude;
@@ -1110,6 +1137,7 @@ public GroupConfig(String group, List<String> pathsToMatch, List<String> package
 			this.producesToMatch = producesToMatch;
 			this.consumesToMatch = consumesToMatch;
 			this.headersToMatch = headersToMatch;
+			this.methodFilters = methodFilters;
 		}
 
 		/**
@@ -1255,5 +1283,23 @@ public List<String> getProducesToMatch() {
 		public void setProducesToMatch(List<String> producesToMatch) {
 			this.producesToMatch = producesToMatch;
 		}
+
+		/**
+		 * Gets the method filters to use.
+		 *
+		 * @return the method filters to use
+		 */
+		public List<MethodFilter> getMethodFilters() {
+			return methodFilters;
+		}
+
+		/**
+		 * Sets the method filters to use.
+		 *
+		 * @param methodFilters the method filters to use
+		 */
+		public void setMethodFilters(List<MethodFilter> methodFilters) {
+			this.methodFilters = methodFilters;
+		}
 	}
 }

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

@@ -116,7 +116,7 @@ public void afterPropertiesSet() {
 		this.groupedOpenApiResources = groupedOpenApis.stream()
 				.collect(Collectors.toMap(GroupedOpenApi::getGroup, item ->
 						{
-							GroupConfig groupConfig = new GroupConfig(item.getGroup(), item.getPathsToMatch(), item.getPackagesToScan(), item.getPackagesToExclude(), item.getPathsToExclude(), item.getProducesToMatch(), item.getConsumesToMatch(),item.getHeadersToMatch());
+							GroupConfig groupConfig = new GroupConfig(item.getGroup(), item.getPathsToMatch(), item.getPackagesToScan(), item.getPackagesToExclude(), item.getPathsToExclude(), item.getProducesToMatch(), item.getConsumesToMatch(),item.getHeadersToMatch(), item.getMethodFilters());
 							springDocConfigProperties.addGroupConfig(groupConfig);
 							return buildWebFluxOpenApiResource(item);
 						}

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

@@ -115,7 +115,7 @@ public void afterPropertiesSet()  {
 		this.groupedOpenApiResources = groupedOpenApis.stream()
 				.collect(Collectors.toMap(GroupedOpenApi::getGroup, item ->
 						{
-							GroupConfig groupConfig = new GroupConfig(item.getGroup(), item.getPathsToMatch(), item.getPackagesToScan(), item.getPackagesToExclude(), item.getPathsToExclude(), item.getProducesToMatch(), item.getConsumesToMatch(), item.getHeadersToMatch());
+							GroupConfig groupConfig = new GroupConfig(item.getGroup(), item.getPathsToMatch(), item.getPackagesToScan(), item.getPackagesToExclude(), item.getPathsToExclude(), item.getProducesToMatch(), item.getConsumesToMatch(), item.getHeadersToMatch(), item.getMethodFilters());
 							springDocConfigProperties.addGroupConfig(groupConfig);
 							return buildWebMvcOpenApiResource(item);
 						}

springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app177/AnnotatedController.java

@@ -0,0 +1,67 @@
+package test.org.springdoc.api.app177;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import org.springdoc.core.GroupedOpenApi;
+import org.springframework.context.annotation.Bean;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class AnnotatedController {
+
+	@Group1
+	@GetMapping("/annotated")
+	public String annotatedGet() {
+		return "annotated";
+	}
+
+	@Group1
+	@PostMapping("/annotated")
+	public String annotatedPost() {
+		return "annotated";
+	}
+
+	@Group2
+	@PutMapping("/annotated")
+	public String annotatedPut() {
+		return "annotated";
+	}
+
+	@Bean
+	public GroupedOpenApi group1OpenApi() {
+		return GroupedOpenApi.builder()
+			.group("annotatedGroup1")
+			.addMethodFilter(method -> method.isAnnotationPresent(Group1.class))
+			.build();
+	}
+
+	@Bean
+	public GroupedOpenApi group2OpenApi() {
+		return GroupedOpenApi.builder()
+			.group("annotatedGroup2")
+			.addMethodFilter(method -> method.isAnnotationPresent(Group2.class))
+			.build();
+	}
+
+	@Bean
+	public GroupedOpenApi group3OpenApi() {
+		return GroupedOpenApi.builder()
+			.group("annotatedCombinedGroup")
+			.addMethodFilter(method -> method.isAnnotationPresent(Group1.class) || method.isAnnotationPresent(Group2.class))
+			.build();
+	}
+
+	@Retention(RetentionPolicy.RUNTIME)
+	@interface Group1 {
+
+	}
+
+	@Retention(RetentionPolicy.RUNTIME)
+	@interface Group2 {
+
+	}
+}

springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app177/SpringDocApp177Test.java

@@ -0,0 +1,67 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  * 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 test.org.springdoc.api.app177;
+
+import static org.hamcrest.Matchers.is;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import org.junit.jupiter.api.Test;
+import org.springdoc.core.Constants;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+import test.org.springdoc.api.AbstractSpringDocTest;
+
+class SpringDocApp177Test extends AbstractSpringDocTest {
+
+	@SpringBootApplication
+	static class SpringDocTestApp {}
+
+	@Test
+	void testFilterOnlyPicksUpMatchedMethods() throws Exception {
+		mockMvc.perform(get(Constants.DEFAULT_API_DOCS_URL + "/annotatedGroup1"))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.openapi", is("3.0.1")))
+			.andExpect(content().json(getContent("results/app177-1.json"), true));
+	}
+
+	@Test
+	void testFilterOnlyPicksUpMatchedMethodsWithDifferentFilter() throws Exception {
+		mockMvc.perform(get(Constants.DEFAULT_API_DOCS_URL + "/annotatedGroup2"))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.openapi", is("3.0.1")))
+			.andExpect(content().json(getContent("results/app177-2.json"), true));
+	}
+
+	@Test
+	void testFilterOnlyPicksUpCombinedMatchedMethods() throws Exception {
+		mockMvc.perform(get(Constants.DEFAULT_API_DOCS_URL + "/annotatedCombinedGroup"))
+			.andExpect(status().isOk())
+			.andExpect(jsonPath("$.openapi", is("3.0.1")))
+			.andExpect(content().json(getContent("results/app177.json"), true));
+	}
+
+}