You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/08/23 08:41:44 UTC
[apisix] branch master updated: docs(plugin): refactor request-validation.md (#7752)
This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new a49f339ff docs(plugin): refactor request-validation.md (#7752)
a49f339ff is described below
commit a49f339ffc2c6dd903b938cabc45c5279a9899c6
Author: Yuedong Wu <57...@users.noreply.github.com>
AuthorDate: Tue Aug 23 16:41:37 2022 +0800
docs(plugin): refactor request-validation.md (#7752)
* docs: update request-validation.md
---
docs/en/latest/plugins/request-validation.md | 27 ++++---
docs/zh/latest/plugins/request-validation.md | 115 +++++++++++++++------------
2 files changed, 77 insertions(+), 65 deletions(-)
diff --git a/docs/en/latest/plugins/request-validation.md b/docs/en/latest/plugins/request-validation.md
index 5ad7b8421..207f4d1d2 100644
--- a/docs/en/latest/plugins/request-validation.md
+++ b/docs/en/latest/plugins/request-validation.md
@@ -2,10 +2,9 @@
title: request-validation
keywords:
- APISIX
- - Plugin
+ - API Gateway
- Request Validation
- - proxy-cache
-description: This document contains information about the Apache APISIX request-validation Plugin.
+description: This document describes the information about the Apache APISIX request-validation Plugin, you can use it to validate the requests before forwarding them to an Upstream service.
---
<!--
@@ -51,7 +50,8 @@ At least one of `header_schema` or `body_schema` should be filled in.
You can configure the Plugin on a specific Route as shown below:
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/5 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
@@ -78,7 +78,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
The examples below shows how you can configure this Plugin for different validation scenarios:
-Enum validation:
+### Enum validation
```json
{
@@ -96,7 +96,7 @@ Enum validation:
}
```
-Boolean validation:
+### Boolean validation
```json
{
@@ -113,7 +113,7 @@ Boolean validation:
}
```
-Number or Integer validation:
+### Number or Integer validation
```json
{
@@ -131,7 +131,7 @@ Number or Integer validation:
}
```
-String validation:
+### String validation
```json
{
@@ -149,7 +149,7 @@ String validation:
}
```
-Regular expression validation:
+### Regular expression validation
```json
{
@@ -168,7 +168,7 @@ Regular expression validation:
}
```
-Array validation:
+### Array validation
```json
{
@@ -192,7 +192,7 @@ Array validation:
}
```
-Combined validation:
+### Combined validation
```json
{
@@ -225,7 +225,7 @@ Combined validation:
}
```
-Custom rejection message:
+### Custom rejection message
```json
{
@@ -270,7 +270,8 @@ curl --header "Content-Type: application/json" \
To disable the `request-validation` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/5 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
diff --git a/docs/zh/latest/plugins/request-validation.md b/docs/zh/latest/plugins/request-validation.md
index 908762d59..dc8332b7d 100644
--- a/docs/zh/latest/plugins/request-validation.md
+++ b/docs/zh/latest/plugins/request-validation.md
@@ -1,5 +1,10 @@
---
title: request-validation
+keywords:
+ - APISIX
+ - API 网关
+ - Request Validation
+description: 本文介绍了 Apache APISIX request-validation 插件的相关操作，你可以使用此插件验证将要转发给上游服务的请求。
---
<!--
@@ -23,27 +28,30 @@ title: request-validation
## 描述
-`request-validation` 插件用于提前验证请求向上游转发请求，可以验证请求的 `body` 及 `header` 数据。
-
-该插件使用 `Json Schema` 进行数据验证，有关 `Json Schema` 的更多信息，请参阅 [JSON schema](https://github.com/api7/jsonschema)。
+`request-validation` 插件用于提前验证向上游服务转发的请求。该插件使用 [JSON Schema](https://github.com/api7/jsonschema) 机制进行数据验证，可以验证请求的 `body` 及 `header` 数据。
## 属性
-> 注意，`header_schema` 与 `body_schema` 至少填写其中一个
-
-| Name | Type | Requirement | Default | Valid | Description |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---------------- | ------ | ----------- | ------- | ----- | --------------------------------- |
-| header_schema | object | 可选 | | | `header` 数据的 `schema` 数据结构 |
-| body_schema | object | 可选 | | | `body` 数据的 `schema` 数据结构 |
-| rejected_code | integer | 可选 | 400 | [200,...,599] | 自定义拒绝状态码 |
-| rejected_msg | string | 可选 | | | 自定义拒绝信息 |
+| header_schema | object | 否 | | | `header` 数据的 `schema` 数据结构。 |
+| body_schema | object | 否 | | | `body` 数据的 `schema` 数据结构。 |
+| rejected_code | integer | 否 | 400 | [200,...,599] | 当请求被拒绝时要返回的状态码。 |
+| rejected_msg | string | 否 | | | 当请求被拒绝时返回的信息。 |
+
+:::note 注意
+
+启用该插件时，至少需要配置 `header_schema` 和 `body_schema` 属性中的任意一个，两者也可以同时使用。
-## 如何启用
+:::
-创建一条路由并在该路由上启用 `request-validation` 插件：
+## 启用插件
+
+以下示例展示了如何在指定路由上启用 `request-validation` 插件，并设置 `body_schema` 字段：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/5 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
@@ -68,39 +76,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## 测试插件
-
-```shell
-curl --header "Content-Type: application/json" \
- --request POST \
- --data '{"boolean-payload":true,"required_payload":"hello"}' \
- http://127.0.0.1:9080/get
-```
-
-如果 `Schema` 验证失败，将返回 `400` 状态码与相应的拒绝信息。
-
-## 禁用插件
-
-在路由 `plugins` 配置块中删除 `request-validation` 配置，即可禁用该插件。
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/get",
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:8080": 1
- }
- }
-}'
-```
-
-## 示例
+以下示例展示了不同验证场景下该插件的 JSON 配置：
-**枚举（Enums）验证：**
+### 枚举（Enum）验证
```json
{
@@ -118,7 +96,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**布尔（Boolean）验证：**
+### 布尔（Boolean）验证
```json
{
@@ -135,7 +113,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**数字范围（Number or Integer）验证：**
+### 数字范围（Number or Integer）验证
```json
{
@@ -153,7 +131,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**字符串长度（String）验证：**
+### 字符串长度（String）验证
```json
{
@@ -171,7 +149,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**正则表达式（Regex）验证：**
+### 正则表达式（Regex）验证
```json
{
@@ -190,7 +168,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**数组（Array）验证：**
+### 数组（Array）验证
```json
{
@@ -214,7 +192,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**多字段组合（Multiple Fields）验证：**
+### 多字段组合（Combined）验证
```json
{
@@ -247,7 +225,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
-**自定义拒绝信息：**
+### 自定义拒绝信息
```json
{
@@ -273,3 +251,36 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
}
```
+
+## 测试插件
+
+按上述配置启用插件后，使用 `curl` 命令请求该路由：
+
+```shell
+curl --header "Content-Type: application/json" \
+ --request POST \
+ --data '{"boolean-payload":true,"required_payload":"hello"}' \
+ http://127.0.0.1:9080/get
+```
+
+现在只允许符合已配置规则的有效请求到达上游服务。不符合配置的请求将被拒绝，并返回 `400` 或自定义状态码。
+
+## 禁用插件
+
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/5 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "plugins": {
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:8080": 1
+ }
+ }
+}'
+```