This is an automated email from the ASF dual-hosted git repository.
Baoyuantop 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 7bc498b56 docs: update fault-injection and mocking plugin
documentation (#13294)
7bc498b56 is described below
commit 7bc498b56475cc9b5e0d25305b88a165ef296fa4
Author: Yilia Lin <[email protected]>
AuthorDate: Tue Apr 28 15:21:13 2026 +0800
docs: update fault-injection and mocking plugin documentation (#13294)
---
docs/en/latest/plugins/fault-injection.md | 302 +++++++++++--------------
docs/en/latest/plugins/mocking.md | 341 ++++++++++++++--------------
docs/zh/latest/plugins/fault-injection.md | 308 +++++++++++---------------
docs/zh/latest/plugins/mocking.md | 354 +++++++++++++++---------------
4 files changed, 598 insertions(+), 707 deletions(-)
diff --git a/docs/en/latest/plugins/fault-injection.md
b/docs/en/latest/plugins/fault-injection.md
index 16d05b13a..ba6724c3d 100644
--- a/docs/en/latest/plugins/fault-injection.md
+++ b/docs/en/latest/plugins/fault-injection.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- Fault Injection
- fault-injection
-description: This document contains information about the Apache APISIX
fault-injection Plugin.
+description: The fault-injection Plugin tests application resiliency by
simulating controlled faults or delays, making it ideal for chaos engineering
and failure condition analysis.
---
<!--
@@ -28,36 +28,43 @@ description: This document contains information about the
Apache APISIX fault-in
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/fault-injection"; />
+</head>
+
## Description
-The `fault-injection` Plugin can be used to test the resiliency of your
application. This Plugin will be executed before the other configured Plugins.
+The `fault-injection` Plugin is designed to test your application's resiliency
by simulating controlled faults or delays. It executes before other configured
Plugins, ensuring that faults are applied consistently. This makes it ideal for
scenarios like chaos engineering, where the behavior of your system under
failure conditions is analyzed.
-The `abort` attribute will directly return the specified HTTP code to the
client and skips executing the subsequent Plugins.
+The Plugin supports two key actions:
-The `delay` attribute delays a request and executes the subsequent Plugins.
+- `abort`: immediately terminates a request with a specified HTTP status code
(e.g., `503 Service Unavailable`), skipping all subsequent Plugins.
+- `delay`: introduces a specified delay before processing the request further.
-## Attributes
+:::info
-| Name | Type | Requirement | Default | Valid |
Description
|
-|-------------------|---------|-------------|---------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| abort.http_status | integer | required | | [200, ...] | HTTP
status code of the response to return to the client.
|
-| abort.body | string | optional | | | Body of
the response returned to the client. Nginx variables like `client addr:
$remote_addr\n` can be used in the body. |
-| abort.headers | object | optional | | | Headers
of the response returned to the client. The values in the header can contain
Nginx variables like `$remote_addr`. |
-| abort.percentage | integer | optional | | [0, 100] |
Percentage of requests to be aborted.
|
-| abort.vars | array[] | optional | | | Rules
which are matched before executing fault injection. See
[lua-resty-expr](https://github.com/api7/lua-resty-expr) for a list of
available expressions. |
-| delay.duration | number | required | | | Duration
of the delay. Can be decimal.
|
-| delay.percentage | integer | optional | | [0, 100] |
Percentage of requests to be delayed.
|
-| delay.vars | array[] | optional | | | Rules
which are matched before executing fault injection. See
[lua-resty-expr](https://github.com/api7/lua-resty-expr) for a list of
available expressions. |
+At least one of `abort` or `delay` must be configured.
-:::info IMPORTANT
+:::
-To use the `fault-injection` Plugin one of `abort` or `delay` must be
specified.
+## Attributes
-:::
+| Name | Type | Required | Default | Valid values |
Description
|
+|-------------------|---------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| abort | object | False | | |
Configuration to abort a request and return a specific HTTP status code to the
client. At least one of `abort` or `delay` must be configured.
|
+| abort.http_status | integer | False | | [200, ...] | HTTP
status code of the response to return to the client. Required when `abort` is
configured.
|
+| abort.body | string | False | | | Body of
the response returned to the client. Supports [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), such as
`client addr: $remote_addr\n`. |
+| abort.headers | object | False | | | Headers of
the response returned to the client. Header values can contain [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), such as
`$remote_addr`. |
+| abort.percentage | integer | False | | [0, 100] | Percentage
of requests to be aborted. If `vars` is also configured, both conditions must
be satisfied.
|
+| abort.vars | array[] | False | | | Rules to
match before aborting a request. Supports
[lua-resty-expr](https://github.com/api7/lua-resty-expr) expressions. Multiple
conditions can be combined with AND/OR logic. |
+| delay | object | False | | |
Configuration to delay a request. At least one of `abort` or `delay` must be
configured.
|
+| delay.duration | number | False | | | Duration
of the delay in seconds. Can be decimal. Required when `delay` is configured.
|
+| delay.percentage | integer | False | | [0, 100] | Percentage
of requests to be delayed. If `vars` is also configured, both conditions must
be satisfied.
|
+| delay.vars | array[] | False | | | Rules to
match before delaying a request. Supports
[lua-resty-expr](https://github.com/api7/lua-resty-expr) expressions. Multiple
conditions can be combined with AND/OR logic. |
:::tip
-`vars` can have expressions from
[lua-resty-expr](https://github.com/api7/lua-resty-expr) and can flexibly
implement AND/OR relationship between rules. For example:
+`vars` supports [lua-resty-expr](https://github.com/api7/lua-resty-expr)
expressions that can flexibly implement AND/OR relationships between rules. For
example:
```json
[
@@ -71,15 +78,16 @@ To use the `fault-injection` Plugin one of `abort` or
`delay` must be specified.
]
```
-This means that the relationship between the first two expressions is AND, and
the relationship between them and the third expression is OR.
+The first two expressions have an AND relationship, and the relationship
between them and the third expression is OR.
:::
-## Enable Plugin
+## Examples
-You can enable the `fault-injection` Plugin on a specific Route as shown below:
+The examples below demonstrate how you can configure `fault-injection` on a
Route in different scenarios.
:::note
+
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -88,206 +96,146 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 200,
- "body": "Fault Injection!"
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
-
-Similarly, to enable a `delay` fault:
+### Inject Faults
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "delay": {
- "duration": 3
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
+The following example demonstrates how to configure the `fault-injection`
Plugin on a Route to intercept requests and respond with a specific HTTP status
code, without forwarding to the Upstream service.
-You can also enable the Plugin with both `abort` and `delay` which can have
`vars` for matching:
+Create a Route with the `fault-injection` Plugin using the `abort` action:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key"
-X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
"plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- },
- "delay": {
- "duration": 2,
- "vars": [
- [
- [ "http_age","==","18" ]
- ]
- ]
- }
+ "fault-injection": {
+ "abort": {
+ "http_status": 404,
+ "body": "APISIX Fault Injection"
}
+ }
},
"upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-## Example usage
-
-Once you have enabled the Plugin as shown above, you can make a request to the
configured Route:
+Send a request to the Route:
```shell
-curl http://127.0.0.1:9080/hello -i
+curl -i "http://127.0.0.1:9080/anything";
```
-```
-HTTP/1.1 200 OK
-Date: Mon, 13 Jan 2020 13:50:04 GMT
-Content-Type: text/plain
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX web server
-
-Fault Injection!
+You should receive an `HTTP/1.1 404 Not Found` response with the following
body, without the request being forwarded to the Upstream service:
+
+```text
+APISIX Fault Injection
```
-And if we configure the `delay` fault:
+### Inject Latencies
+
+The following example demonstrates how to configure the `fault-injection`
Plugin on a Route to inject request latency.
+
+Create a Route with the `fault-injection` Plugin using the `delay` action to
delay responses by 3 seconds:
```shell
-time curl http://127.0.0.1:9080/hello -i
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
+ "plugins": {
+ "fault-injection": {
+ "delay": {
+ "duration": 3
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
+Send a request to the Route and use `time` to measure how long it takes:
+
+```shell
+time curl -i "http://127.0.0.1:9080/anything";
```
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 6
-Connection: keep-alive
-Server: APISIX web server
-Date: Tue, 14 Jan 2020 14:30:54 GMT
-Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT
-hello
+You should receive an `HTTP/1.1 200 OK` response from the Upstream service,
and the timing summary should show approximately 3 seconds total:
+```text
real 0m3.034s
user 0m0.007s
sys 0m0.010s
```
-### Fault injection with criteria matching
+### Inject Faults Conditionally
-You can enable the `fault-injection` Plugin with the `vars` attribute to set
specific rules:
+The following example demonstrates how to configure the `fault-injection`
Plugin on a Route to inject faults only when specific request conditions are
met.
+
+Create a Route with the `fault-injection` Plugin configured to abort requests
only when the URL parameter `name` equals `john`:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key"
-X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
"plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- }
+ "fault-injection": {
+ "abort": {
+ "http_status": 404,
+ "body": "APISIX Fault Injection",
+ "headers": {
+ "X-APISIX-Remote-Addr": "$remote_addr"
+ },
+ "vars": [
+ [
+ [ "arg_name","==","john" ]
+ ]
+ ]
}
+ }
},
"upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-Now, we can test the Route. First, we test with a different `name` argument:
+Send a request to the Route with the URL parameter `name` set to `john`:
```shell
-curl "http://127.0.0.1:9080/hello?name=allen"; -i
+curl -i "http://127.0.0.1:9080/anything?name=john";
```
-You will get the expected response without the fault injected:
+You should receive an `HTTP/1.1 404 Not Found` response similar to the
following:
-```
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 07:21:57 GMT
-Server: APISIX/2.2
-
-hello
-```
-
-Now if we set the `name` to match our configuration, the `fault-injection`
Plugin is executed:
-
-```shell
-curl "http://127.0.0.1:9080/hello?name=jack"; -i
-```
+```text
+HTTP/1.1 404 Not Found
+...
+X-APISIX-Remote-Addr: 192.168.65.1
+APISIX Fault Injection
```
-HTTP/1.1 403 Forbidden
-Date: Wed, 20 Jan 2021 07:23:37 GMT
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.2
-
-Fault Injection!
-```
-
-## Delete Plugin
-To remove the `fault-injection` 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.
+Send a request with a different `name` value:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "uri": "/hello",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl -i "http://127.0.0.1:9080/anything?name=jane";
```
+
+You should receive an `HTTP/1.1 200 OK` response from the Upstream service,
without faults injected.
diff --git a/docs/en/latest/plugins/mocking.md
b/docs/en/latest/plugins/mocking.md
index 97080a5e4..3a2a4edb7 100644
--- a/docs/en/latest/plugins/mocking.md
+++ b/docs/en/latest/plugins/mocking.md
@@ -5,7 +5,8 @@ keywords:
- API Gateway
- Plugin
- Mocking
-description: This document contains information about the Apache APISIX
mocking Plugin.
+ - mocking
+description: The mocking Plugin simulates API responses without forwarding
requests to upstream services, offering customization of status codes, response
bodies, headers, and more for API testing and development.
---
<!--
@@ -27,23 +28,27 @@ description: This document contains information about the
Apache APISIX mocking
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/mocking"; />
+</head>
+
## Description
-The `mocking` Plugin is used for mocking an API. When executed, it returns
random mock data in the format specified and the request is not forwarded to
the Upstream.
+The `mocking` Plugin allows you to simulate API responses without forwarding
requests to Upstream services. The Plugin supports customization of the
response status code, body, headers, and more. This is particularly useful
during development, testing, or debugging phases, where the actual Upstream
service might be unavailable, under maintenance, or expensive to call.
## Attributes
-| Name | Type | Required | Default | Description
|
-|------------------|---------|----------|------------------|----------------------------------------------------------------------------------------|
-| delay | integer | False | | Response delay in
seconds. |
-| response_status | integer | False | 200 | HTTP status code
of the response. |
-| content_type | string | False | application/json | Header
`Content-Type` of the response.
|
-| response_example | string | False | | Body of the
response, support use variables, like `$remote_addr $consumer_name`. |
-| response_schema | object | False | | The JSON schema
object for the response. Works when `response_example` is unspecified. |
-| with_mock_header | boolean | False | true | When set to
`true`, adds a response header `x-mock-by: APISIX/{version}`. |
-| response_headers | object | false | | Headers to be
added in the mocked response. Example: `{"X-Foo": "bar", "X-Few": "baz"}`|
+| Name | Type | Required | Default
| Description
|
+|------------------|---------|----------------------------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| delay | integer | False | 0
| Response delay in seconds.
|
+| response_status | integer | False | 200
| HTTP status code of the response.
|
+| content_type | string | False |
application/json;charset=utf8 | `Content-Type` header value of the response.
|
+| response_example | string | One of this or `response_schema` |
| Body of the response. Supports [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), such as
`$remote_addr`. One of `response_example` or `response_schema` must be
configured, and they must not be configured together. |
+| response_schema | object | One of this or `response_example` |
| A [JSON schema](https://json-schema.org) object to generate
a random mock response body. One of `response_schema` or `response_example`
must be configured, and they must not be configured together. |
+| with_mock_header | boolean | False | true
| When set to `true`, adds a response header `x-mock-by:
APISIX/{version}`.
|
+| response_headers | object | False |
| Headers to be added in the mocked response. For example:
`{"X-Foo": "bar"}`.
|
-The JSON schema supports the following types in their fields:
+The `response_schema` supports the following field types:
- `string`
- `number`
@@ -52,81 +57,12 @@ The JSON schema supports the following types in their
fields:
- `object`
- `array`
-Here is a JSON schema example:
-
-```json
-{
- "properties":{
- "field0":{
- "example":"abcd",
- "type":"string"
- },
- "field1":{
- "example":123.12,
- "type":"number"
- },
- "field3":{
- "properties":{
- "field3_1":{
- "type":"string"
- },
- "field3_2":{
- "properties":{
- "field3_2_1":{
- "example":true,
- "type":"boolean"
- },
- "field3_2_2":{
- "items":{
- "example":155.55,
- "type":"integer"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- },
- "type":"object"
- },
- "field2":{
- "items":{
- "type":"string"
- },
- "type":"array"
- }
- },
- "type":"object"
-}
-```
-
-This is the response generated by the Plugin from this JSON schema:
-
-```json
-{
- "field1": 123.12,
- "field3": {
- "field3_1": "LCFE0",
- "field3_2": {
- "field3_2_1": true,
- "field3_2_2": [
- 155,
- 155
- ]
- }
- },
- "field0": "abcd",
- "field2": [
- "sC"
- ]
-}
-```
+## Examples
-## Enable Plugin
-
-The example below configures the `mocking` Plugin for a specific Route:
+The examples below demonstrate how you can configure `mocking` on a Route in
different scenarios.
:::note
+
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -135,116 +71,181 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### Generate Specific Mock Responses
+
+The following example demonstrates how to configure the Plugin to generate a
specific mock response and response status code without forwarding the request
to the Upstream service.
+
+Create a Route with the `mocking` Plugin:
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
"plugins": {
- "mocking": {
- "delay": 1,
- "content_type": "application/json",
- "response_status": 200,
- "response_schema": {
- "properties":{
- "field0":{
- "example":"abcd",
- "type":"string"
- },
- "field1":{
- "example":123.12,
- "type":"number"
- },
- "field3":{
- "properties":{
- "field3_1":{
- "type":"string"
- },
- "field3_2":{
- "properties":{
- "field3_2_1":{
- "example":true,
- "type":"boolean"
- },
- "field3_2_2":{
- "items":{
- "example":155.55,
- "type":"integer"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- },
- "type":"object"
- },
- "field2":{
- "items":{
- "type":"string"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- }
+ "mocking": {
+ "response_status": 201,
+ "response_example": "{\"Lastname\":\"Brown\",\"Age\":56}"
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
```
-## Example usage
+Send a request to the Route:
-Once you have configured the Plugin as mentioned above, you can test the Route.
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
-The example used here uses this mocked response:
+You should receive an `HTTP/1.1 201 Created` mock response with the following
body:
-```json
-{
- "delay":0,
- "content_type":"",
- "with_mock_header":true,
- "response_status":201,
- "response_example":"{\"a\":1,\"b\":2}"
-}
+```text
+{"Lastname":"Brown","Age":56}
```
-Now to test the Route:
+### Generate Mock Response Headers
+
+The following example demonstrates how to configure the Plugin to generate
mock response headers and use a built-in NGINX variable in the response body.
+
+Create a Route with the `mocking` Plugin:
```shell
-curl http://127.0.0.1:9080/test-mock -i
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
+ "plugins": {
+ "mocking": {
+ "response_headers": {
+ "X-User-Id": "100",
+ "X-Product-Id": "apac-398-472"
+ },
+ "response_example": "Client IP: $remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
+Send a request to the Route:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
```
-HTTP/1.1 201 Created
-...
-Content-Type: application/json;charset=utf8
-x-mock-by: APISIX/2.10.0
+
+You should receive a response similar to the following:
+
+```text
+HTTP/1.1 200 OK
...
+X-Product-Id: apac-398-472
+X-User-Id: 100
-{"a":1,"b":2}
+Client IP: 192.168.65.1
```
-## Delete Plugin
+### Generate Mock Responses Using JSON Schema
+
+The following example demonstrates how to configure the Plugin to generate
mock responses following a specific [JSON schema](https://json-schema.org).
-To remove the `mocking` 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.
+Create a Route with the `mocking` Plugin and define a JSON schema for the
expected mock responses:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
+ "plugins": {
+ "mocking": {
+ "response_schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "example": "abcd"
+ },
+ "ip": {
+ "type": "number",
+ "example": 192.168
+ },
+ "random_str_arr": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "nested_obj": {
+ "type": "object",
+ "properties": {
+ "random_str": {
+ "type": "string"
+ },
+ "child_nested_obj": {
+ "type": "object",
+ "properties": {
+ "random_bool": {
+ "type": "boolean",
+ "example": true
+ },
+ "random_int_arr": {
+ "type": "array",
+ "items": {
+ "type": "integer",
+ "example": 155
+ }
+ }
+ }
+ }
+ }
+ }
+ }
}
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
+```
+
+Send a request to the Route:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
+
+You should see a mock response similar to the following, without an actual
response from the Upstream service:
+
+```text
+{
+ "ip": 192.168,
+ "random_str_arr": [
+ "fb", "lyquibkwc", "r"
+ ],
+ "id": "abcd",
+ "nested_obj": {
+ "random_str": "bzbb",
+ "child_nested_obj": {
+ "random_bool": true,
+ "random_int_arr": [155, 155, 155]
+ }
+ }
+}
```
diff --git a/docs/zh/latest/plugins/fault-injection.md
b/docs/zh/latest/plugins/fault-injection.md
index c0ae512cd..f6afa71b8 100644
--- a/docs/zh/latest/plugins/fault-injection.md
+++ b/docs/zh/latest/plugins/fault-injection.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- Fault Injection
- fault-injection
-description: 本文介绍了关于 Apache APISIX `fault-injection` 插件的基本信息及使用方法。
+description: fault-injection 插件通过模拟受控故障或延迟来测试应用程序的弹性，非常适合混沌工程和故障条件分析场景。
---
<!--
@@ -28,36 +28,43 @@ description: 本文介绍了关于 Apache APISIX `fault-injection` 插件的基
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/fault-injection"; />
+</head>
+
## 描述
-`fault-injection` 插件是故障注入插件，该插件可以和其他插件一起使用，并在其他插件执行前被执行。
+`fault-injection`
插件通过模拟受控故障或延迟来测试应用程序的弹性。该插件在其他已配置插件之前执行，确保故障被一致性地应用。这使其非常适合混沌工程等场景，用于分析系统在故障条件下的行为。
-## 属性
+该插件支持两种主要操作：
-| 名称 | 类型 | 必选项 | 有效值 | 描述 |
-| ----------------- | ------- | ---- | ---------- |
-------------------------- |
-| abort.http_status | integer | 是 | [200, ...] | 返回给客户端的 HTTP 状态码 |
-| abort.body | string | 否 | | 返回给客户端的响应数据。支持使用 NGINX
变量，如 `client addr: $remote_addr\n`|
-| abort.headers | object | 否 | | 返回给客户端的响应头，可以包含 NGINX 变量，如
`$remote_addr` |
-| abort.percentage | integer | 否 | [0, 100] | 将被中断的请求占比 |
-| abort.vars | array[] | 否 | |
执行故障注入的规则，当规则匹配通过后才会执行故障注。`vars` 是一个表达式的列表，来自
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)。 |
-| delay.duration | number | 是 | | 延迟时间，可以指定小数 |
-| delay.percentage | integer | 否 | [0, 100] | 将被延迟的请求占比 |
-| delay.vars | array[] | 否 | |
执行请求延迟的规则，当规则匹配通过后才会延迟请求。`vars` 是一个表达式列表，来自
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)。 |
+- `abort`：立即以指定的 HTTP 状态码（例如 `503 Service Unavailable`）终止请求，跳过所有后续插件。
+- `delay`：在进一步处理请求之前引入指定的延迟。
-:::info IMPORTANT
+:::info
-`abort` 属性将直接返回给客户端指定的响应码并且终止其他插件的执行。
+`abort` 和 `delay` 至少需要配置其中一个。
-`delay` 属性将延迟某个请求，并且还会执行配置的其他插件。
+:::
-`abort` 和 `delay` 属性至少要配置一个。
+## 属性
-:::
+| 名称 | 类型 | 必选项 | 有效值 | 描述
|
+|-------------------|---------|--------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| abort | object | 否 | | 终止请求并向客户端返回特定 HTTP
状态码的配置。`abort` 和 `delay` 至少需要配置其中一个。
|
+| abort.http_status | integer | 否 | [200, ...] | 返回给客户端的 HTTP 状态码。配置
`abort` 时必填。
|
+| abort.body | string | 否 | | 返回给客户端的响应体。支持使用 [NGINX
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，例如 `client addr:
$remote_addr\n`。 |
+| abort.headers | object | 否 | | 返回给客户端的响应头。标头值可包含 [NGINX
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，例如
`$remote_addr`。 |
+| abort.percentage | integer | 否 | [0, 100] | 被终止的请求占比。若同时配置了
`vars`，则两个条件都必须满足。
|
+| abort.vars | array[] | 否 | | 终止请求前需匹配的规则。支持
[lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式，可通过 AND/OR
逻辑组合多个条件。 |
+| delay | object | 否 | | 延迟请求的配置。`abort` 和
`delay` 至少需要配置其中一个。
|
+| delay.duration | number | 否 | | 延迟时长（秒），可以为小数。配置 `delay`
时必填。
|
+| delay.percentage | integer | 否 | [0, 100] | 被延迟的请求占比。若同时配置了
`vars`，则两个条件都必须满足。
|
+| delay.vars | array[] | 否 | | 延迟请求前需匹配的规则。支持
[lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式，可通过 AND/OR
逻辑组合多个条件。 |
:::tip
-`vars` 是由 [`lua-resty-expr`](https://github.com/api7/lua-resty-expr)
的表达式组成的列表，它可以灵活的实现规则之间的 AND/OR 关系，示例如下：：
+`vars` 支持 [lua-resty-expr](https://github.com/api7/lua-resty-expr)
表达式，可灵活实现规则之间的 AND/OR 关系。示例：
```json
[
@@ -71,17 +78,17 @@ description: 本文介绍了关于 Apache APISIX `fault-injection` 插件的基
]
```
-以上示例表示前两个表达式之间的关系是 AND，而前两个和第三个表达式之间的关系是 OR。
+以上示例中，前两个表达式之间是 AND 关系，而它们与第三个表达式之间是 OR 关系。
:::
-## 启用插件
+## 示例
-你可以在指定路由启用 `fault-injection` 插件，并指定 `abort` 属性。如下所示：
+下面的示例演示了如何在不同场景中在路由上配置 `fault-injection`。
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -89,211 +96,146 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### 注入故障
+
+以下示例演示如何在路由上配置 `fault-injection` 插件，拦截请求并以指定 HTTP 状态码响应，不转发请求到上游服务。
+
+使用 `abort` 操作创建带有 `fault-injection` 插件的路由：
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
"plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 200,
- "body": "Fault Injection!"
- }
- }
+ "fault-injection": {
+ "abort": {
+ "http_status": 404,
+ "body": "APISIX Fault Injection"
+ }
+ }
},
"upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-同样，我们也可以指定 `delay` 属性。如下所示：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "delay": {
- "duration": 3
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+curl -i "http://127.0.0.1:9080/anything";
```
-还可以同时为指定路由启用 `fault-injection` 插件，并指定 `abort` 属性和 `delay` 属性的 `vars` 规则。如下所示：
+你应该收到 `HTTP/1.1 404 Not Found` 响应，并看到以下响应体，请求不会被转发到上游服务：
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- },
- "delay": {
- "duration": 2,
- "vars": [
- [
- [ "http_age","==","18" ]
- ]
- ]
- }
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
+```text
+APISIX Fault Injection
```
-## 测试插件
+### 注入延迟
-通过上述示例启用插件后，可以向路由发起如下请求：
+以下示例演示如何在路由上配置 `fault-injection` 插件以注入请求延迟。
-```shell
-curl http://127.0.0.1:9080/hello -i
-```
+使用 `delay` 操作创建带有 `fault-injection` 插件的路由，将响应延迟 3 秒：
```shell
-HTTP/1.1 200 OK
-Date: Mon, 13 Jan 2020 13:50:04 GMT
-Content-Type: text/plain
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX web server
-
-Fault Injection!
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
+ "plugins": {
+ "fault-injection": {
+ "delay": {
+ "duration": 3
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-通过如下命令可以向配置 `delay` 属性的路由发起请求：
+向路由发送请求，并使用 `time` 计时：
```shell
-time curl http://127.0.0.1:9080/hello -i
+time curl -i "http://127.0.0.1:9080/anything";
```
-```shell
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 6
-Connection: keep-alive
-Server: APISIX web server
-Date: Tue, 14 Jan 2020 14:30:54 GMT
-Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT
-
-hello
+你应该收到来自上游服务的 `HTTP/1.1 200 OK` 响应，计时摘要应显示约 3 秒总耗时：
+```text
real 0m3.034s
user 0m0.007s
sys 0m0.010s
```
-### 标准匹配的故障注入
+### 条件注入故障
+
+以下示例演示如何在路由上配置 `fault-injection` 插件，仅在满足特定请求条件时注入故障。
-你可以在 `fault-injection` 插件中使用 `vars` 规则设置特定规则：
+创建带有 `fault-injection` 插件的路由，配置仅当 URL 参数 `name` 等于 `john` 时才终止请求：
-```Shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "fault-injection-route",
+ "uri": "/anything",
"plugins": {
- "fault-injection": {
- "abort": {
- "http_status": 403,
- "body": "Fault Injection!\n",
- "vars": [
- [
- [ "arg_name","==","jack" ]
- ]
- ]
- }
+ "fault-injection": {
+ "abort": {
+ "http_status": 404,
+ "body": "APISIX Fault Injection",
+ "headers": {
+ "X-APISIX-Remote-Addr": "$remote_addr"
+ },
+ "vars": [
+ [
+ [ "arg_name","==","john" ]
+ ]
+ ]
}
+ }
},
"upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
-
-使用不同的 `name` 参数测试路由：
-
-```Shell
-curl "http://127.0.0.1:9080/hello?name=allen"; -i
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-没有故障注入的情况下，你可以得到如下结果：
+发送 URL 参数 `name` 为 `john` 的请求：
```shell
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Wed, 20 Jan 2021 07:21:57 GMT
-Server: APISIX/2.2
-
-hello
+curl -i "http://127.0.0.1:9080/anything?name=john";
```
-如果我们将 `name` 设置为与配置相匹配的名称，`fault-injection` 插件将被执行：
+你应该收到类似以下的 `HTTP/1.1 404 Not Found` 响应：
-```Shell
-curl "http://127.0.0.1:9080/hello?name=jack"; -i
-```
+```text
+HTTP/1.1 404 Not Found
+...
+X-APISIX-Remote-Addr: 192.168.65.1
-```shell
-HTTP/1.1 403 Forbidden
-Date: Wed, 20 Jan 2021 07:23:37 GMT
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX/2.2
-
-Fault Injection!
+APISIX Fault Injection
```
-## 删除插件
-
-当你需要禁用 `fault-injection` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+发送 `name` 为其他值的请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/hello",
- "plugins": {},
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
+curl -i "http://127.0.0.1:9080/anything?name=jane";
```
+
+你应该收到来自上游服务的 `HTTP/1.1 200 OK` 响应，没有注入故障。
diff --git a/docs/zh/latest/plugins/mocking.md
b/docs/zh/latest/plugins/mocking.md
index 17ca3a716..2c7880a7e 100644
--- a/docs/zh/latest/plugins/mocking.md
+++ b/docs/zh/latest/plugins/mocking.md
@@ -5,7 +5,8 @@ keywords:
- API 网关
- Plugin
- Mocking
-description: 本文介绍了关于 Apache APISIX `mocking` 插件的基本信息及使用方法。
+ - mocking
+description: mocking 插件无需转发请求到上游服务即可模拟 API 响应，支持自定义状态码、响应体、标头等，适用于 API 测试和开发场景。
---
<!--
@@ -27,23 +28,31 @@ description: 本文介绍了关于 Apache APISIX `mocking` 插件的基本信息
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/mocking"; />
+</head>
+
## 描述
-`mocking` 插件用于模拟 API。当执行该插件时，它将随机返回指定格式的模拟数据，并且请求不会转发到上游。
+`mocking` 插件允许你在不将请求转发到上游服务的情况下模拟 API
响应。该插件支持自定义响应状态码、响应体、响应头等。在开发、测试或调试阶段，当实际上游服务不可用、正在维护或调用成本较高时，该插件尤为有用。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 描述
|
-| ------------- | -------| ----- | ---------------- |
--------------------------------------------------------------------------- |
-| delay | integer| 否 | | 延时返回的时间，单位为秒。
|
-| response_status | integer| 否 | 200 | 返回响应的 HTTP 状态码。
|
-| content_type | string | 否 | application/json | 返回响应的 Header
`Content-Type`。 |
-| response_example| string | 否 | | 返回响应的 Body，支持使用变量，例如
`$remote_addr $consumer_name`，与 `response_schema` 字段二选一。 |
-| response_schema | object | 否 | | 指定响应的 `jsonschema`
对象，未指定 `response_example` 字段时生效。 |
-| with_mock_header| boolean| 否 | true | 当设置为 `true` 时，将添加响应头
`x-mock-by: APISIX/{version}`。设置为 `false` 时则不添加该响应头。 |
-| response_headers| object | 否 | |
要在模拟响应中添加的标头。示例：`{"X-Foo": "bar", "X-Few": "baz"}`
|
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+|------------------|---------|--------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| delay | integer | 否 | 0 |
延迟返回响应的时间，单位为秒。
|
+| response_status | integer | 否 | 200 | 响应的
HTTP 状态码。
|
+| content_type | string | 否 | application/json;charset=utf8 | 响应的
`Content-Type` 标头值。
|
+| response_example | string | 二选一 | | 响应体内容。支持
[NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，例如
`$remote_addr`。与 `response_schema` 二选一，且至少配置其中一个，不能同时配置。 |
+| response_schema | object | 二选一 | |
用于生成随机模拟响应体的 [JSON Schema](https://json-schema.org) 对象。与 `response_example`
二选一，且至少配置其中一个，不能同时配置。 |
+| with_mock_header | boolean | 否 | true | 设置为
`true` 时，将添加响应头 `x-mock-by: APISIX/{version}`。
|
+| response_headers | object | 否 | |
要添加到模拟响应中的标头。例如：`{"X-Foo": "bar"}`。
|
-JSON Schema 在其字段中支持以下类型：
+:::note
+`response_example` 与 `response_schema` 不能同时配置，且至少需要配置其中一个，否则插件配置将无法通过校验。
+:::
+
+`response_schema` 支持以下字段类型：
- `string`
- `number`
@@ -52,83 +61,13 @@ JSON Schema 在其字段中支持以下类型：
- `object`
- `array`
-以下是一个 JSON Schema 示例：
-
-```json
-{
- "properties":{
- "field0":{
- "example":"abcd",
- "type":"string"
- },
- "field1":{
- "example":123.12,
- "type":"number"
- },
- "field3":{
- "properties":{
- "field3_1":{
- "type":"string"
- },
- "field3_2":{
- "properties":{
- "field3_2_1":{
- "example":true,
- "type":"boolean"
- },
- "field3_2_2":{
- "items":{
- "example":155.55,
- "type":"integer"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- },
- "type":"object"
- },
- "field2":{
- "items":{
- "type":"string"
- },
- "type":"array"
- }
- },
- "type":"object"
-}
-```
+## 示例
-以下为上述 JSON Schema 可能生成的返回对象：
-
-```json
-{
- "field1": 123.12,
- "field3": {
- "field3_1": "LCFE0",
- "field3_2": {
- "field3_2_1": true,
- "field3_2_2": [
- 155,
- 155
- ]
- }
- },
- "field0": "abcd",
- "field2": [
- "sC"
- ]
-}
-```
-
-## 启用插件
-
-你可以通过如下命令在指定路由上启用 `mocking` 插件：
+下面的示例演示了如何在不同场景中在路由上配置 `mocking`。
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -136,120 +75,181 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### 生成特定模拟响应
+
+以下示例演示如何配置插件以生成特定的模拟响应和响应状态码，而不将请求转发到上游服务。
+
+创建带有 `mocking` 插件的路由：
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
"plugins": {
- "mocking": {
- "delay": 1,
- "content_type": "application/json",
- "response_status": 200,
- "response_schema": {
- "properties":{
- "field0":{
- "example":"abcd",
- "type":"string"
- },
- "field1":{
- "example":123.12,
- "type":"number"
- },
- "field3":{
- "properties":{
- "field3_1":{
- "type":"string"
- },
- "field3_2":{
- "properties":{
- "field3_2_1":{
- "example":true,
- "type":"boolean"
- },
- "field3_2_2":{
- "items":{
- "example":155.55,
- "type":"integer"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- },
- "type":"object"
- },
- "field2":{
- "items":{
- "type":"string"
- },
- "type":"array"
- }
- },
- "type":"object"
- }
- }
+ "mocking": {
+ "response_status": 201,
+ "response_example": "{\"Lastname\":\"Brown\",\"Age\":56}"
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
```
-## 测试插件
+向路由发送请求：
-通过上述命令启用插件后，可以使用如下方式测试插件是否启用成功：
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
-当 `mocking` 插件配置如下：
+你应该收到 `HTTP/1.1 201 Created` 模拟响应，响应体如下：
-```JSON
-{
- "delay":0,
- "content_type":"",
- "with_mock_header":true,
- "response_status":201,
- "response_example":"{\"a\":1,\"b\":2}"
-}
+```text
+{"Lastname":"Brown","Age":56}
+```
+
+### 生成模拟响应标头
+
+以下示例演示如何配置插件以生成模拟响应标头，并在响应体中使用内置的 NGINX 变量。
+
+创建带有 `mocking` 插件的路由：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
+ "plugins": {
+ "mocking": {
+ "response_headers": {
+ "X-User-Id": "100",
+ "X-Product-Id": "apac-398-472"
+ },
+ "response_example": "Client IP: $remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+ }'
```
-通过如下命令进行测试：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9080/test-mock -i
+curl -i "http://127.0.0.1:9080/anything";
```
-```Shell
-HTTP/1.1 201 Created
-Date: Fri, 14 Jan 2022 11:49:34 GMT
-Content-Type: application/json;charset=utf8
-Transfer-Encoding: chunked
-Connection: keep-alive
-x-mock-by: APISIX/2.10.0
-Server: APISIX/2.10.0
+你应该收到类似以下内容的响应：
-{"a":1,"b":2}
+```text
+HTTP/1.1 200 OK
+...
+X-Product-Id: apac-398-472
+X-User-Id: 100
+
+Client IP: 192.168.65.1
```
-## 删除插件
+### 使用 JSON Schema 生成模拟响应
+
+以下示例演示如何配置插件以按照特定的 [JSON Schema](https://json-schema.org) 生成模拟响应。
-当你需要禁用 `mocking` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+创建带有 `mocking` 插件的路由，并定义 JSON Schema：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mocking-route",
+ "uri": "/anything",
+ "plugins": {
+ "mocking": {
+ "response_schema": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "example": "abcd"
+ },
+ "ip": {
+ "type": "number",
+ "example": 192.168
+ },
+ "random_str_arr": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "nested_obj": {
+ "type": "object",
+ "properties": {
+ "random_str": {
+ "type": "string"
+ },
+ "child_nested_obj": {
+ "type": "object",
+ "properties": {
+ "random_bool": {
+ "type": "boolean",
+ "example": true
+ },
+ "random_int_arr": {
+ "type": "array",
+ "items": {
+ "type": "integer",
+ "example": 155
+ }
+ }
+ }
+ }
+ }
+ }
+ }
}
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
+```
+
+向路由发送请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
+
+你应该看到类似以下内容的模拟响应，而非来自上游服务的实际响应：
+
+```text
+{
+ "ip": 192.168,
+ "random_str_arr": [
+ "fb", "lyquibkwc", "r"
+ ],
+ "id": "abcd",
+ "nested_obj": {
+ "random_str": "bzbb",
+ "child_nested_obj": {
+ "random_bool": true,
+ "random_int_arr": [155, 155, 155]
+ }
+ }
+}
```
