GH-3366: Document HTTP request mapping limitation (#3382)

* GH-3366: Document HTTP request mapping limitation

Fixes #3366

The same path cannot be mapped both Spring Integration and MVC ways

* Doc Polishing

Co-authored-by: Gary Russell <grussell@pivotal.io>

Author: artembilan

spring-integration-http/src/main/java/org/springframework/integration/http/inbound/IntegrationRequestMappingHandlerMapping.java

@@ -21,6 +21,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 import javax.servlet.http.HttpServletRequest;
@@ -78,6 +79,14 @@
  * register HTTP endpoints at runtime for dynamically declared beans, e.g. via
  * {@link org.springframework.integration.dsl.context.IntegrationFlowContext}, and unregister
  * them during the {@link BaseHttpInboundEndpoint} destruction.
+ *<p>
+ * This class extends the Spring MVC {@link RequestMappingHandlerMapping} class, inheriting
+ * most of its logic, especially {@link #handleNoMatch(Set, String, HttpServletRequest)},
+ * which throws a specific {@code 4xx} error for the HTTP response, when mapping doesn't match
+ * for some reason, preventing calls to any remaining mapping handlers in the application context.
+ * For this reason, configuring the same path for both Spring Integration and
+ * Spring MVC request mappings (e.g. `POST` in one and `GET` in the other) is not supported;
+ * the MVC mapping will not be found.
  *
  * @author Artem Bilan
  * @author Gary Russell

src/reference/asciidoc/http.adoc

@@ -349,6 +349,9 @@ The following example shows how to do so:
 
 For more information regarding handler mappings, see https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html[the Spring Framework Web Servlet documentation] or https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html[the Spring Framework Web Reactive documentation].
 
+IMPORTANT: The `IntegrationRequestMappingHandlerMapping` extends the Spring MVC `RequestMappingHandlerMapping` class, inheriting most of its logic, especially `handleNoMatch(Set, String, HttpServletRequest)`, which throws a specific `4xx` error for the HTTP response, when mapping doesn't match for some reason, preventing calls to any remaining mapping handlers in the application context.
+For this reason, configuring the same path for both Spring Integration and Spring MVC request mappings (e.g. `POST` in one and `GET` in the other) is not supported; the MVC mapping will not be found..
+
 [[http-cors]]
 ==== Cross-origin Resource Sharing (CORS) Support