DATAREST-1381 - Improve documentation around @RepositoryRestController.

spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestController.java

@@ -21,11 +21,22 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.springframework.orm.jpa.support.OpenEntityManagerInViewInterceptor;
 import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.HandlerMapping;
 
 /**
  * Annotation to demarcate Spring MVC controllers provided by Spring Data REST. Allows to easily detect them and exclude
  * them from standard Spring MVC handling.
+ * <p>
+ * Note, that this annotation should only be used by application controllers that map to URIs that are managed by Spring
+ * Data REST as the get handled by a special {@link HandlerMapping} implementation that applies additional
+ * functionality:
+ * <ul>
+ * <li>CORS configuration defined for the repository backing the path.</li>
+ * <li>An {@link OpenEntityManagerInViewInterceptor} for JPA backed repositories so that properties can always be
+ * accessed.</li>
+ * </ul>
  *
  * @author Oliver Gierke
  */

src/main/asciidoc/overriding-sdr-response-handlers.adoc

@@ -48,6 +48,14 @@ public class ScannerController {
 
 IMPORTANT: In this example, the combined path is `RepositoryRestConfiguration.getBasePath()` + `/scanners/search/listProducers`.
 
+[[customizing-sdr.overriding-sdr-response-handlers.annotations]]
+== @RepositoryRestResource VS. @BasePathAwareController
+
 If you are not interested in entity-specific operations but still want to build custom operations underneath `basePath`, such as Spring MVC views, resources, and others, use `@BasePathAwareController`.
+If you're using `@RepositoryRestResource` on your custom controller, it will only handle the request if your request mappings blend into the URI space used by the repository.
+It will also apply the following extra functionality to the controller methods:
+
+. CORS configuration according as defined for the repository mapped to the base path segment used in the request mapping of the handler method.
+. Apply an `OpenEntityManagerInViewInterceptor` if JPA is used to make sure you can access properties marked as to be resolved lazily.
 
 WARNING: If you use `@Controller` or `@RestController` for anything, that code is totally outside the scope of Spring Data REST. This extends to request handling, message converters, exception handling, and other uses.