From ddd65e338a6da90e2656fbc4fe8df605ce5c0654 Mon Sep 17 00:00:00 2001
From: Dave Syer <dsyer@pivotal.io>
Date: Fri, 30 Jun 2017 15:50:15 +0100
Subject: [PATCH] Add some docs

---
 README.adoc                                   | 20 +++++++++
 docs/src/main/asciidoc/intro.adoc             |  2 +-
 .../main/asciidoc/spring-cloud-gateway.adoc   | 43 +++++++++++++++++--
 3 files changed, 61 insertions(+), 4 deletions(-)

diff --git a/README.adoc b/README.adoc
index a6d25806..f15b9315 100644
--- a/README.adoc
+++ b/README.adoc
@@ -11,6 +11,26 @@ This project provides a library for building an API Gateway on top of the Spring
 == Features
 
 * Spring Boot 1.5
+* Spring MVC `@RestController` method injection of a `ProxyExchange`
+* Build up complex routing and request enhancement using the standard Spring Web toolkit
+
+Example (proxying a request to "/test" downstream to a remote server):
+
+```java
+@RestController
+@SpringBootApplication
+public class GatewaySampleApplication {
+
+	@Value("${remote.home}")
+	private URI home;
+
+	@GetMapping("/test")
+	public ResponseEntity<?> proxy(ProxyExchange<Object> proxy) throws Exception {
+		return proxy.uri(home.toString() + "/image/png").get();
+	}
+
+}
+```
 
 == Building
 
diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc
index 0c932f68..9efa6e9f 100644
--- a/docs/src/main/asciidoc/intro.adoc
+++ b/docs/src/main/asciidoc/intro.adoc
@@ -1,2 +1,2 @@
-This project provides a library for building an API Gateway on top of the Spring MVC. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.
+This project provides a library for building an API Gateway on top of Spring MVC. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.
 
diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc
index 3a6e21da..5871c220 100644
--- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc
@@ -14,7 +14,44 @@ include::intro.adoc[]
 [[gateway-starter]]
 == How to Include Spring Cloud Gateway
 
-To include Spring Cloud Gateway in your project use the starter with group `org.springframework.cloud`
-and artifact id `spring-cloud-gateway-mvc`. See the http://projects.spring.io/spring-cloud/[Spring Cloud Project page]
-for details on setting up your build system with the current Spring Cloud Release Train.
+To include Spring Cloud Gateway in your project add a dependency with group `org.springframework.cloud` and artifact id `spring-cloud-gateway-mvc`. See the http://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
 
+== Building a Gateway Using Spring MVC
+
+Spring Cloud Gateway provides a utility object called `ProxyExchange` which you can use inside a regular Spring MVC handler as a method parameter. It supports basic downstream HTTP exchanges via methods that mirror the HTTP verbs, or forwarding to a local handler via the `forward()` method.
+
+Example (proxying a request to "/test" downstream to a remote server):
+
+```java
+@RestController
+@SpringBootApplication
+public class GatewaySampleApplication {
+
+	@Value("${remote.home}")
+	private URI home;
+
+	@GetMapping("/test")
+	public ResponseEntity<?> proxy(ProxyExchange<Object> proxy) throws Exception {
+		return proxy.uri(home.toString() + "/image/png").get();
+	}
+
+}
+```
+
+There are convenience methods on the `ProxyExchange` to enable the handler method to discover and enhance the URI path of the incoming request. For example you might want to extract the trailing elements of a path to pass them downstream:
+
+```java
+@GetMapping("/proxy/path/**")
+public ResponseEntity<?> proxyPath(ProxyExchange<?> proxy) throws Exception {
+  String path = proxy.path("/proxy/path/");
+  return proxy.uri(home.toString() + "/foos/" + path).get();
+}
+```
+
+All the features of Spring MVC are available to Gateway handler methods. So you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation. See the documentation for `@RequestMapping` in Spring MVC for more details of those features.
+
+Headers can be added to the downstream response using the `header()` methods on `ProxyExchange`.
+
+You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the `get()` etc. method. The mapper is a `Function` that takes the incoming `ResponseEntity` and converts it to an outgoing one.
+
+First class support is provided for "sensitive" headers ("cookie" and "authorization" by default) which are not passed downstream, and for "proxy" headers (`x-forwarded-*`).
\ No newline at end of file