From ffed1fd41231bd73d375543ccb5b49f6ac63ae55 Mon Sep 17 00:00:00 2001 From: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Date: Mon, 25 Nov 2024 13:44:02 -0800 Subject: [PATCH] fix: Request Validator incorrectly refers to Kong format schema (#8111) * fix mention of Kong schema vs json schema; clean up page * Apply suggestions from code review --- .../request-validator/overview/_index.md | 140 +++++------------- 1 file changed, 34 insertions(+), 106 deletions(-) diff --git a/app/_hub/kong-inc/request-validator/overview/_index.md b/app/_hub/kong-inc/request-validator/overview/_index.md index 42da2581efd3..89c45874fe70 100644 --- a/app/_hub/kong-inc/request-validator/overview/_index.md +++ b/app/_hub/kong-inc/request-validator/overview/_index.md @@ -2,11 +2,11 @@ nav_title: Overview --- -Validate requests before they reach their upstream service. Supports validating +Validate requests before they reach their upstream service. This plugin supports validating the schema of the body and the parameters of the request using either Kong's own schema validator (body only) or a JSON Schema Draft 4 compliant validator. -## Content-Type Validation +## Content-Type validation The request Content-Type header is validated against the plugin's [`allowed_content_types`](/hub/kong-inc/request-validator/configuration/#config-allowed_content_types) setting. If the request Content-Type is not listed, the request will be rejected with an HTTP/400 error: `{"message":"specified Content-Type is not allowed"}` @@ -15,7 +15,7 @@ The parameter is strictly validated, which means a request with a parameter (for {:.important} > When setting this configuration, the `Content-Type` header only gets validated when `body_schema` is configured. -## Body Validation +## Body validation {% if_version lte:3.5.x %} Request body validation is only performed for requests with `application/json` Content-Type. @@ -30,7 +30,7 @@ For requests with any other allowed Content-Type, body validation is skipped. In ### Overview -By applying the plugin to a Service, all requests to that Service will be validated +By applying the plugin to a service, all requests to that service will be validated before being proxied. {% navtabs %} @@ -70,7 +70,7 @@ to contain a `name` field only, which needs to be a string. In case the validation fails, a `400 Bad Request` will be returned as the response. -### Schema Definition +### Schema definition *For using the JSON Schema Draft 4-compliant validator, see the [JSON Schema website]( https://json-schema.org/) for details on the format and examples. The rest of @@ -97,7 +97,7 @@ Map: Example string-boolean map: -``` +```json { "type": "map", "keys": { @@ -117,7 +117,7 @@ Array: Example integer array schema: -``` +```json { "type": "array", "elements": { @@ -134,7 +134,7 @@ Record: Example record schema: -``` +```json { "type": "record", "fields": [ @@ -184,7 +184,7 @@ validations: **Note**: To learn more, see [Lua patterns][lua-patterns]. -#### Semantic validation for `format` attribute +#### Semantic validation for the JSON Schema `format` attribute {:.important} > This feature is only supported in JSON Schema Draft 4. @@ -205,16 +205,16 @@ external specifications. The following attributes are available: Example `date` schema: -``` +```json { "type": "string", "format": "date" } ``` -### Kong Schema Example +### JSON Schema example -``` +```json [ { "name": { @@ -260,7 +260,7 @@ Example `date` schema: Such a schema would validate the following request body: -``` +```json { "name": "Gruce The Great", "age": 4, @@ -273,14 +273,14 @@ Such a schema would validate the following request body: ``` -### Parameter Schema Definition +### Parameter schema definition -You can setup definitions for each parameter based on the OpenAPI Specification and +You can set up definitions for each parameter based on the OpenAPI Specification and the plugin will validate each parameter against it. For more information, see the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameter-object) or the [OpenAPI examples](https://swagger.io/docs/specification/serialization/). -#### Fixed Fields +#### Fixed fields |Field Name | Type | Description| | --- | --- | --- | @@ -295,107 +295,31 @@ or the [OpenAPI examples](https://swagger.io/docs/specification/serialization/). In this example, use the plugin to validate a request's path parameter. -1. Add a Service to Kong: +1. Add a service to Kong: - ``` + ```sh curl -i -X POST http://localhost:8001/services \ --data name=httpbin \ --data url=https://httpbin.konghq.com - - HTTP/1.1 201 Created - .. - - { - "host":"httpbin.konghq.com", - "created_at":1563479714, - "connect_timeout":60000, - "id":"0a7f3795-bc92-43b5-aada-258113b7c4ed", - "protocol":"http", - "name":"httpbin", - "read_timeout":60000, - "port":80, - "path":null, - "updated_at":1563479714, - "retries":5, - "write_timeout":60000 - } ``` -2. Add a Route with [named capture group](/gateway/latest/how-kong-works/routing-traffic/#capturing-groups): +2. Add a route with [named capture group](/gateway/latest/how-kong-works/routing-traffic/#capturing-groups): - ``` + ```sh curl -i -X POST http://localhost:8001/services/httpbin/routes \ --data paths="~/status/(?\d%+)" \ --data strip_path=false - - HTTP/1.1 201 Created - .. - - { - "created_at": 1563481399, - "methods": null, - "id": "cd78749a-33a3-4bbd-9560-588eaf4116d3", - "service": { - "id": "0a7f3795-bc92-43b5-aada-258113b7c4ed" - }, - "name": null, - "hosts": null, - "updated_at": 1563481399, - "preserve_host": false, - "regex_priority": 0, - "paths": [ - "\\/status\\/(?\\d+)" - ], - "sources": null, - "destinations": null, - "snis": null, - "protocols": [ - "http", - "https" - ], - "strip_path": false - } ``` 3. Enable `request-validator` plugin to validate body and parameter: - ``` + ```sh curl -i -X POST http://localhost:8001/services/httpbin/plugins \ --header "Content-Type: application/json" \ --data @parameter_schema.json - - HTTP/1.1 201 Created - .. - - { - "created_at": 1563483059, - "config": { - "body_schema": "{\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}", - "parameter_schema": [ - { - "style": "simple", - "required": true, - "in": "path", - "schema": "{\"type\": \"number\"}", - "explode": false, - "name": "status_code" - } - ], - "version": "draft4" - }, - "id": "ad91a2d4-6217-4d34-9133-4a2508ddda9f", - "service": { - "id": "0a7f3795-bc92-43b5-aada-258113b7c4ed" - }, - "enabled": true, - "run_on": "first", - "consumer": null, - "route": null, - "name": "request-validator" - } ``` - Content of file `parameter_schema.json`: + Content of the file `parameter_schema.json`: ```json { @@ -419,13 +343,17 @@ In this example, use the plugin to validate a request's path parameter. 4. In these step examples, validation ensures that `status_code` is a number and the body contains a parameter called `name`. - A proxy request with a non-numerical status code is blocked: + For example, if you try to send a request to an existing route with the path `/status/abc`: - ``` + ```sh curl -i -X POST \ --url http://localhost:8000/status/abc \ --header 'Content-Type: application/json' \ --data '{ "name": "foo" }' + ``` + + The proxy request is blocked because the path has a non-numerical status code, which doesn't conform to the schema: + ``` HTTP/1.1 400 Bad Request ... @@ -434,19 +362,19 @@ In this example, use the plugin to validate a request's path parameter. A proxy request with a numeric status code is allowed: - ``` + ```sh curl -i -X POST \ --url http://localhost:8000/status/123 \ --header 'Content-Type: application/json' \ --data '{ "name": "foo" }' - HTTP/1.1 200 OK - X-Kong-Upstream-Latency: 163 - X-Kong-Proxy-Latency: 37 - ... + ``` + Response: + ``` + HTTP/1.1 200 OK ``` -### Further References +### Further references The Kong schema validation format is based on the plugin schemas. For more information, see the Kong plugin docs on