diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/actuator-api.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/actuator-api.adoc index ada53bbe1..2ea374984 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/actuator-api.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/actuator-api.adoc @@ -91,7 +91,7 @@ This feature is enabled by default. To disable it, set the following property: .application.properties [source,properties] ---- -spring.cloud.gateway.actuator.verbose.enabled=false +spring.cloud.gateway.server.webflux.actuator.verbose.enabled=false ---- This will default to `true` in a future release. @@ -181,29 +181,29 @@ Sending `POST` request to `/actuator/gateway/refresh?metadata=group:group-1` wil == Retrieving the Routes Defined in the Gateway To retrieve the routes defined in the gateway, make a `GET` request to `/actuator/gateway/routes`. -The resulting response is similar to the following: +The resulting response is similar to the following (verbose format, which is the default): ---- [{ + "predicate": "Paths: [/first], match trailing slash: true", "route_id": "first_route", - "route_object": { - "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@1e9d7e7d", - "filters": [ - "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" - ] - }, + "filters": [ + "[[PreserveHostHeader], order = 0]" + ], + "uri": "https://www.uri-destination.org", "order": 0 }, { + "predicate": "Paths: [/second], match trailing slash: true", "route_id": "second_route", - "route_object": { - "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298", - "filters": [] - }, + "filters": [], + "uri": "https://www.uri-destination.org", "order": 0 }] ---- +NOTE: When `spring.cloud.gateway.server.webflux.actuator.verbose.enabled=false`, predicates and filters are shown as raw Java class strings instead of human-readable descriptions. + The response contains the details of all the routes defined in the gateway. The following table describes the structure of each element (each is a route) of the response: @@ -215,14 +215,18 @@ The following table describes the structure of each element (each is a route) of | String | The route ID. -|`route_object.predicate` -| Object -| The route predicate. +|`predicate` +| String +| A human-readable string representation of the route predicates (verbose format). -|`route_object.filters` +|`filters` | Array | The xref:spring-cloud-gateway-server-webflux/gatewayfilter-factories.adoc[`GatewayFilter` factories] applied to the route. +|`uri` +| String +| The destination URI of the route. + |`order` | Number | The route order. @@ -233,17 +237,20 @@ The following table describes the structure of each element (each is a route) of == Retrieving Information about a Particular Route To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/\{id}` (for example, `/actuator/gateway/routes/first_route`). +The resulting response is similar to the following: ---- { "route_id": "first_route", - "predicate": "(Paths: [/first], match trailing slash: true && Methods: [GET])", + "predicate": "(Paths: [/first], match trailing slash: true)", "filters": [], "uri": "https://www.uri-destination.org", "order": 0 } ---- +NOTE: The response format for `GET /actuator/gateway/routes/{id}` represents predicates as a single human-readable string. This is different from the shortcut DSL string format required when creating routes via `POST`. See <> for the correct POST request body format. + The following table describes the structure of the response: [cols="3,2,4"] @@ -254,9 +261,9 @@ The following table describes the structure of the response: | String | The route ID. -|`predicates` -| Array -| The collection of route predicates. Each item defines the name and the arguments of a given predicate. +|`predicate` +| String +| A human-readable string representation of the route predicates. |`filters` | Array @@ -275,9 +282,37 @@ The following table describes the structure of the response: [[creating-and-deleting-a-particular-route-definition]] == Creating and Deleting a Particular Route Definition -To create a route definition, make a `POST` request to `/gateway/routes/\{id_route_to_create}` with a JSON body that specifies the fields of the route (see xref:spring-cloud-gateway-server-webflux/actuator-api.adoc#gateway-retrieving-information-about-a-particular-route[Retrieving Information about a Particular Route]). +WARNING: Only routes created through the actuator endpoint can be modified or deleted via these endpoints. +Routes defined in application configuration (for example, `application.yml` or via `@Bean`) are read-only from the actuator's perspective. +Attempting to delete a configuration-defined route will return `404 Not Found`. -To delete a route definition, make a `DELETE` request to `/gateway/routes/\{id_route_to_delete}`. +To create a route definition, make a `POST` request to `/actuator/gateway/routes/\{id_route_to_create}` with a JSON body specifying the route fields. +Predicates and filters must be provided as shortcut DSL strings (for example, `"Path=/foo/**"` or `"StripPrefix=1"`), which is different from the structured format returned by `GET /actuator/gateway/routes/\{id}`. +The following example shows the correct request format: + +---- +{ + "predicates": ["Path=/mypath/**", "Weight=mygroup,20"], + "filters": ["StripPrefix=1"], + "uri": "http://backend-service:8080", + "order": 0 +} +---- + +A successful creation returns `201 Created`. +After creating a route, call `POST /actuator/gateway/refresh` to apply the change without restarting the application. + +WARNING: Do *not* `POST` to an existing route ID without first deleting it. +Doing so duplicates the route definition internally, which causes a `500 Internal Server Error` on subsequent `GET /actuator/gateway/routes` requests. +To update an existing actuator-managed route, you must delete it first and then recreate it: + +. Send `DELETE` to `/actuator/gateway/routes/\{id}`. +. Send `POST` to `/actuator/gateway/routes/\{id}` with the updated definition. +. Send `POST` to `/actuator/gateway/refresh`. + +To delete a route definition, make a `DELETE` request to `/actuator/gateway/routes/\{id_route_to_delete}`. +A successful deletion returns `200 OK`. +After deleting a route, call `POST /actuator/gateway/refresh` to apply the change without restarting the application. [[creating-multiple-route-definitions]] == Creating multiple Route Definitions @@ -317,10 +352,10 @@ The following table below summarizes the Spring Cloud Gateway actuator endpoints |`routes/\{id}` |POST -| Adds a new route to the gateway. +| Adds a new route to the gateway. Uses shortcut DSL string format for predicates and filters. Returns `201 Created` on success. |`routes/\{id}` |DELETE -| Removes an existing route from the gateway. +| Removes an existing route from the gateway. Routes defined in application configuration cannot be removed via this endpoint (returns `404 Not Found`). -|=== +|=== \ No newline at end of file