diff --git a/README.adoc b/README.adoc index 42522912..a6d25806 100644 --- a/README.adoc +++ b/README.adoc @@ -5,21 +5,12 @@ image::https://codecov.io/gh/spring-cloud-incubator/spring-cloud-gateway/branch/ image::https://api.codacy.com/project/badge/Grade/a6885a06921e4f72a0df0b7aabd6d118["Codacy code quality", link="https://www.codacy.com/app/spring-cloud-incubator/spring-cloud-gateway?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud-incubator/spring-cloud-gateway&utm_campaign=Badge_Grade"] -This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 5, Spring Boot 2 and Project Reactor. 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 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. == Features -* Java 8 -* Spring Framework 5 -* Spring Boot 2 -* Dynamic routing -* Route matching built into Spring Handler Mapping -* Route matching on HTTP Request (Path, Method, Header, Host, etc...) -* Filters scoped to Matching Route -* Filters can modify downstream HTTP Request and HTTP Response (Add/Remove Headers, Add/Remove Parameters, Rewrite Path, Set Path, Hystrix, etc...) -* API or configuration driven -* Supports Spring Cloud `DiscoveryClient` for configuring Routes +* Spring Boot 1.5 == Building diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc index e66341e6..0c932f68 100644 --- a/docs/src/main/asciidoc/intro.adoc +++ b/docs/src/main/asciidoc/intro.adoc @@ -1,2 +1,2 @@ -This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 5, Spring Boot 2 and Project Reactor. 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 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. diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index b3446ceb..3a6e21da 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -15,213 +15,6 @@ include::intro.adoc[] == 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-starter-gateway`. See the http://projects.spring.io/spring-cloud/[Spring Cloud Project page] +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. -Include the `@EnableGateway` annotation on any `@Configuration` class to enable Spring Cloud Gateway. - -== Glossary - -TODO: document the meaning of terms to follow, like Route, Predicate and Filter - -[[gateway-how-it-works]] -== How It Works - -TODO: give an overview of how the gateway works with maybe a ascii diagram - -[[gateway-request-predicates-factories]] -== Route Predicate Factories - -Spring Cloud Gateway matches routes as part of the Spring WebFlux `HandlerMapping` infrastructure. Spring Cloud Gateway includes many built-in Route Predicate Factorys. All of these predicates match on different attributes of the HTTP request. Multiple Route Predicate Factorys can be combined and are combined via logical `and`. - -=== After Route Predicate Factory -TODO: document After Route Predicate Factory - -=== Before Route Predicate Factory -TODO: document Before Route Predicate Factory - -=== Between Route Predicate Factory -TODO: document Between Route Predicate Factory - -=== Cookie Route Predicate Factory -The Cookie Route Predicate Factory takes two parameters, the cookie name and a regular expression. This predicate matches cookies that have the given name and the value matches the regular expression. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # ===================================== - - id: cookie_route - uri: http://example.org - predicates: - - Cookie=chocolate, ch.p ----- - -This route matches the request has a cookie named `chocolate` who's value matches the `ch.p` regular expression. - -=== Header Route Predicate Factory -The Header Route Predicate Factory takes two parameters, the header name and a regular expression. This predicate matches with a header that has the given name and the value matches the regular expression. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # ===================================== - - id: header_route - uri: http://example.org - predicates: - - Header=X-Request-Id, \d+ ----- - -This route matches if the request has a header named `X-Request-Id` whos value matches the `\d+` regular expression (has a value of one or more digits). - -=== Host Route Predicate Factory -The Host Route Predicate Factory takes one parameter: the host name pattern. The pattern is an Ant style pattern with `.` as the separator. This predicates matches the `Host` header that matches the pattern. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # ===================================== - - id: host_route - uri: http://example.org - predicates: - - Host=**.somehost.org ----- - -This route would match if the request has a `Host` header has the value `www.somehost.org` or `beta.somehost.org`. - - -=== Method Route Predicate Factory -The Method Route Predicate Factory takes one parameter: the HTTP method to match. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # ===================================== - - id: method_route - uri: http://example.org - predicates: - - Method=GET ----- - -This route would match if the request method was a `GET`. - -=== Path Route Predicate Factory -The Path Route Predicate Factory takes one parameter: a Spring `PathMatcher` pattern. - -.application.yml -[source,yaml] ----- -spring: - cloud: - gateway: - routes: - # ===================================== - - id: host_route - uri: http://example.org - predicates: - - Path=/foo/{segment} ----- - -This route would match if the request path was, for example: `/foo/1` or `/foo/bar`. - -This predicate extracts the URI template variables (like `segment` defined in the example above) as a map of names and values and places it in the `ServerWebExchange.getAttributes()` with a key defined in `PathRoutePredicate.URL_PREDICATE_VARS_ATTR`. Those values are then available for use by <> - -=== Query Route Predicate Factory -TODO: document Query Route Predicate Factory - -=== RemoteAddr Route Predicate Factory -TODO: document RemoteAddr Route Predicate Factory - -[[gateway-route-filters]] -== WebFilter Factorys - -Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. Route filters are scoped to a particular route. Spring Cloud Gateway includes many built-in WebFilter Factories. - -=== AddRequestHeader WebFilter Factory -TODO: document AddRequestHeader WebFilter Factory - -=== AddRequestParameter WebFilter Factory -TODO: document AddRequestParameter WebFilter Factory - -=== AddResponseHeader WebFilter Factory -TODO: document AddResponseHeader WebFilter Factory - -=== Hystrix WebFilter Factory -TODO: document Hystrix WebFilter Factory - -=== PrefixPath WebFilter Factory -TODO: document PrefixPath WebFilter Factory - -=== RedirectTo WebFilter Factory -TODO: document RedirectTo WebFilter Factory - -=== RemoveNonProxyHeaders WebFilter Factory -TODO: document RemoveNonProxyHeaders WebFilter Factory - -=== RemoveRequestHeader WebFilter Factory -TODO: document RemoveRequestHeader WebFilter Factory - -=== RemoveResponseHeader WebFilter Factory -TODO: document RemoveResponseHeader WebFilter Factory - -=== RewritePath WebFilter Factory -TODO: document RewritePath WebFilter Factory - -=== SecureHeaders WebFilter Factory -TODO: document SecureHeaders WebFilter Factory - -=== SetPath WebFilter Factory -TODO: document SetPath WebFilter Factory - -=== SetResponseHeader WebFilter Factory -TODO: document SetResponseHeader WebFilter Factory - -=== SetStatus WebFilter Factory -TODO: document SetStatus WebFilter Factory - -== Global Filters - -TODO: document Global Filters - -== Configuration - -TODO: document configuration via Spring Boot external properties - -== Actuator API - -TODO: document the `/gateway` actuator endpoint - -== Developer Guide - -TODO: overview of writing custom integrations - -=== Writing Custom Route Predicate Factorys - -TODO: document writing Custom Route Predicate Factorys - -=== Writing Custom WebFilter Factorys - -TODO: document writing Custom WebFilter Factorys - -=== Writing Custom Global Filters - -TODO: document writing Custom Global Filters - -=== Writing Custom Route Locators and Writers - -TODO: document writing Custom Route Locators and Writers