From 7791dd1a94782bf694f067ed4d0d1eececd4a874 Mon Sep 17 00:00:00 2001
From: Mathieu Fortin <mathieufortin01@gmail.com>
Date: Wed, 13 Jun 2018 15:06:46 -0400
Subject: [PATCH] RequestRateLimiter documentation.

Fixes #168
---
 .../main/asciidoc/spring-cloud-gateway.adoc   | 34 ++++++++++++++++---
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc
index ffa7b422..90af8609 100644
--- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc
@@ -450,9 +450,11 @@ This will prefix `/mypath` to the path of all matching requests. So a request to
 
 The RequestRateLimiter GatewayFilter Factory takes three parameters: `replenishRate`, `burstCapacity` & `keyResolverName`.
 
-`replenishRate` is how many requests per second do you want a user to be allowed to do.
+`replenishRate` is how many requests per second do you want a user to be allowed to do, without any dropped requests.
 
-`burstCapacity` TODO: document burst capacity
+`burstCapacity` is the maximum number of requests a user is allowed to do in a single second. 
+
+A steady rate is accomplished by setting the same value in `replenishRate` and `burstCapacity`. Temporary bursts can be allowed by setting `burstCapacity` higher than `replenishRate`. In this case, the rate limiter needs to be allowed some time between bursts (according to `replenishRate`), as 2 consecutive bursts will result in dropped requests (`HTTP 429 - Too Many Requests`).
 
 `keyResolver` is a bean that implements the `KeyResolver` interface. In configuration, reference the bean by name using SpEL. `#{@myKeyResolver}` is a SpEL expression referencing a bean with the name `myKeyResolver`.
 
@@ -479,7 +481,12 @@ spring:
       - id: requestratelimiter_route
         uri: http://example.org
         filters:
-        - RequestRateLimiter=10, 20, #{@userKeyResolver}
+        - name: RequestRateLimiter
+          args:
+            redis-rate-limiter.replenishRate: 10
+            redis-rate-limiter.burstCapacity: 20
+            key-resolver: "#{@userKeyResolver}"
+
 ----
 
 .Config.java
@@ -491,7 +498,26 @@ KeyResolver userKeyResolver() {
 }
 ----
 
-This defines a request rate limit of 10 per user. The `KeyResolver` is a simple one that gets the `user` request parameter (note: this is not recommended for production).
+This defines a request rate limit of 10 per user. A burst of 20 is allowed, but the next second only 10 requests will be available. The `KeyResolver` is a simple one that gets the `user` request parameter (note: this is not recommended for production).
+
+A rate limiter can also be defined as a bean implementing the `RateLimiter` interface. In configuration, reference the bean by name using SpEL. `#{@myRateLimiter}` is a SpEL expression referencing a bean with the name `myRateLimiter`.
+
+.application.yml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      routes:
+      - id: requestratelimiter_route
+        uri: http://example.org
+        filters:
+        - name: RequestRateLimiter
+          args:
+            rate-limiter: "#{@myRateLimiter}"
+            key-resolver: "#{@userKeyResolver}"
+
+----
 
 === RedirectTo GatewayFilter Factory
 The RedirectTo GatewayFilter Factory takes a `status` and a `url` parameter. The status should be a 300 series redirect http code, such as 301. The url should be a valid url. This will be the value of the `Location` header.