docs: improve public-api plugin docs

docs/en/latest/plugins/public-api.md

@@ -42,6 +42,8 @@ The `public-api` Plugin exposes an internal API endpoint, making it publicly acc
 
 ## Example
 
+The examples below demonstrate how you can configure `public-api` in different scenarios.
+
 ### Expose Prometheus Metrics at Custom Endpoint
 
 The following example demonstrates how you can disable the Prometheus export server that, by default, exposes an endpoint on port `9091`, and expose APISIX Prometheus metrics on a new public API endpoint on port `9080`, which APISIX uses to listen to other client requests.
@@ -67,9 +69,10 @@ plugin_attr:
 Next, create a Route with the `public-api` Plugin and expose a public API endpoint for APISIX metrics. You should set the Route `uri` to the custom endpoint path and set the Plugin `uri` to the internal endpoint to be exposed.
 
 ```shell
-curl "http://127.0.0.1:9180/apisix/admin/routes/prometheus-metrics" -X PUT \
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
   -H "X-API-KEY: ${admin_key}" \
   -d '{
+    "id": "prometheus-metrics",
     "uri": "/prometheus_metrics",
     "plugins": {
       "public-api": {
@@ -101,3 +104,142 @@ apisix_nginx_http_current_connections{state="waiting"} 0
 apisix_nginx_http_current_connections{state="writing"} 1
 ...
 ```
+
+### Expose Batch Requests Endpoint
+
+The following example demonstrates how you can use the `public-api` Plugin to expose an endpoint for the `batch-requests` Plugin, which is used for assembling multiple requests into one single request before sending them to the gateway.
+
+[//]:<TODO: update link to batch-requests plugin doc when it is available>
+
+Create a sample Route to httpbin's `/anything` endpoint for verification purpose:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "httpbin-anything",
+    "uri": "/anything",
+    "upstream": {
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
+    }
+  }'
+```
+
+Create a Route with `public-api` Plugin and set the Route `uri` to the internal endpoint to be exposed:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "batch-requests",
+    "uri": "/apisix/batch-requests",
+    "plugins": {
+      "public-api": {}
+    }
+  }'
+```
+
+Send a pipelined request consisting of a GET and a POST request to the exposed batch requests endpoint:
+
+```shell
+curl "http://127.0.0.1:9080/apisix/batch-requests" -X POST -d '
+{
+  "pipeline": [
+    {
+      "method": "GET",
+      "path": "/anything"
+    },
+    {
+      "method": "POST",
+      "path": "/anything",
+      "body": "a post request"
+    }
+  ]
+}'
+```
+
+You should receive responses from both requests, similar to the following:
+
+```json
+[
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"GET\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  },
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"a post request\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Content-Length\": \"14\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"POST\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  }
+]
+```
+
+If you would like to expose the batch requests endpoint at a custom endpoint, create a Route with `public-api` Plugin as such. You should set the Route `uri` to the custom endpoint path and set the plugin `uri` to the internal endpoint to be exposed.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "batch-requests",
+    "uri": "/batch-requests",
+    "plugins": {
+      "public-api": {
+        "uri": "/apisix/batch-requests"
+      }
+    }
+  }'
+```
+
+The batch requests endpoint should now be exposed as `/batch-requests`, instead of `/apisix/batch-requests`.
+
+Send a pipelined request consisting of a GET and a POST request to the exposed batch requests endpoint:
+
+```shell
+curl "http://127.0.0.1:9080/batch-requests" -X POST -d '
+{
+  "pipeline": [
+    {
+      "method": "GET",
+      "path": "/anything"
+    },
+    {
+      "method": "POST",
+      "path": "/anything",
+      "body": "a post request"
+    }
+  ]
+}'
+```
+
+You should receive responses from both requests, similar to the following:
+
+```json
+[
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"GET\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  },
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"a post request\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Content-Length\": \"14\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"POST\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  }
+]
+```

docs/zh/latest/plugins/public-api.md

@@ -42,6 +42,8 @@ description: public-api 插件公开了一个内部 API 端点，使其可被公
 
 ## 示例
 
+以下示例展示了如何在不同场景中配置 `public-api`。
+
 ### 在自定义端点暴露 Prometheus 指标
 
 以下示例演示如何禁用默认在端口 `9091` 上暴露端点的 Prometheus 导出服务器，并在 APISIX 用于监听其他客户端请求的端口 `9080` 上，通过新的公共 API 端点暴露 APISIX 的 Prometheus 指标。
@@ -67,9 +69,10 @@ plugin_attr:
 接下来，创建一个带有 `public-api` 插件的路由，并为 APISIX 指标暴露一个公共 API 端点。你应将路由的 `uri` 设置为自定义端点路径，并将插件的 `uri` 设置为要暴露的内部端点。
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/prometheus-metrics -X PUT \
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
   -H 'X-API-KEY: ${admin_key}' \
   -d '{
+    "id": "prometheus-metrics",
     "uri": "/prometheus_metrics",
     "plugins": {
       "public-api": {
@@ -101,3 +104,139 @@ apisix_nginx_http_current_connections{state="waiting"} 0
 apisix_nginx_http_current_connections{state="writing"} 1
 ...
 ```
+
+### 暴露批量请求端点
+
+以下示例展示了如何使用 `public-api` 插件来暴露 `batch-requests` 插件的端点，该插件用于将多个请求组合成一个请求，然后将它们发送到网关。
+
+创建一个样本路由到 httpbin 的 `/anything` 端点，用于验证目的：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "httpbin-anything",
+    "uri": "/anything",
+    "upstream": {
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
+    }
+  }'
+```
+
+创建一个带有 `public-api` 插件的路由，并将路由的 `uri` 设置为要暴露的内部端点：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "batch-requests",
+    "uri": "/apisix/batch-requests",
+    "plugins": {
+      "public-api": {}
+    }
+  }'
+```
+
+向暴露的批量请求端点发送一个包含 GET 和 POST 请求的流水线请求：
+
+```shell
+curl "http://127.0.0.1:9080/apisix/batch-requests" -X POST -d '
+{
+  "pipeline": [
+    {
+      "method": "GET",
+      "path": "/anything"
+    },
+    {
+      "method": "POST",
+      "path": "/anything",
+      "body": "a post request"
+    }
+  ]
+}'
+```
+
+您应该会收到两个请求的响应，类似于以下内容：
+
+```json
+[
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"GET\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  },
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"a post request\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Content-Length\": \"14\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"POST\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  }
+]
+```
+
+如果您希望在自定义端点处暴露批量请求端点，请创建一个带有 `public-api` 插件的路由。您应该将路由的 `uri` 设置为自定义端点路径，并将插件的 uri 设置为要暴露的内部端点。
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "batch-requests",
+    "uri": "/batch-requests",
+    "plugins": {
+      "public-api": {
+        "uri": "/apisix/batch-requests"
+      }
+    }
+  }'
+```
+
+现在批量请求端点应该被暴露为 `/batch-requests`，而不是 `/apisix/batch-requests`。
+向暴露的批量请求端点发送一个包含 GET 和 POST 请求的流水线请求：
+
+```shell
+curl "http://127.0.0.1:9080/batch-requests" -X POST -d '
+{
+  "pipeline": [
+    {
+      "method": "GET",
+      "path": "/anything"
+    },
+    {
+      "method": "POST",
+      "path": "/anything",
+      "body": "a post request"
+    }
+  ]
+}'
+```
+
+您应该会收到两个请求的响应，类似于以下内容：
+
+```json
+[
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"GET\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  },
+  {
+    "reason": "OK",
+    "body": "{\n  \"args\": {}, \n  \"data\": \"a post request\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Accept\": \"*/*\", \n    \"Content-Length\": \"14\", \n    \"Host\": \"127.0.0.1\", \n    \"User-Agent\": \"curl/8.6.0\", \n    \"X-Amzn-Trace-Id\": \"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n    \"X-Forwarded-Host\": \"127.0.0.1\"\n  }, \n  \"json\": null, \n  \"method\": \"POST\", \n  \"origin\": \"192.168.107.1, 43.252.208.84\", \n  \"url\": \"http://127.0.0.1/anything\"\n}\n",
+    "headers": {
+      ...
+    },
+    "status": 200
+  }
+]
+```