[apisix] branch master updated: docs: improve CSRF plugin's documentation (#7519)

[juzhiyuan]

This is an automated email from the ASF dual-hosted git repository.

juzhiyuan 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 d38d19984 docs: improve CSRF plugin's documentation (#7519)
d38d19984 is described below

commit d38d19984c249f51648620ed3f41d4b10631e505
Author: Yuedong Wu <57584831+lunarwh...@users.noreply.github.com>
AuthorDate: Fri Jul 29 09:03:36 2022 +0800

    docs: improve CSRF plugin's documentation (#7519)
---
 docs/en/latest/plugins/csrf.md |  2 +-
 docs/zh/latest/plugins/csrf.md | 61 +++++++++++++++++++++++++-----------------
 2 files changed, 38 insertions(+), 25 deletions(-)

diff --git a/docs/en/latest/plugins/csrf.md b/docs/en/latest/plugins/csrf.md
index 3285f5121..bb963d187 100644
--- a/docs/en/latest/plugins/csrf.md
+++ b/docs/en/latest/plugins/csrf.md
@@ -5,7 +5,7 @@ keywords:
   - Plugin
   - Cross-site request forgery
   - csrf
-description: This document contains information about the Apache APISIX csrf 
Plugin.
+description: The CSRF Plugin can be used to protect your API against CSRF 
attacks using the Double Submit Cookie method.
 ---
 
 <!--
diff --git a/docs/zh/latest/plugins/csrf.md b/docs/zh/latest/plugins/csrf.md
index 00fff4d61..6dd5c4eaf 100644
--- a/docs/zh/latest/plugins/csrf.md
+++ b/docs/zh/latest/plugins/csrf.md
@@ -1,5 +1,13 @@
 ---
 title: csrf
+keywords:
+  - APISIX
+  - API 网关
+  - 跨站请求伪造攻击
+  - Cross-site request forgery
+  - csrf
+description: CSRF 插件基于 Double Submit Cookie 的方式，帮助用户阻止跨站请求伪造攻击。
+
 ---
 
 <!--
@@ -23,23 +31,21 @@ title: csrf
 
 ## 描述
 
-`CSRF` 插件基于 [`Double Submit 
Cookie`](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie)
 的方式，保护您的 API 免于 CSRF 攻击。本插件认为 `GET`、`HEAD` 和 `OPTIONS` 方法是安全操作。因此 `GET`、`HEAD` 
和 `OPTIONS` 方法的调用不会被检查拦截。
+`csrf` 插件基于 [`Double Submit 
Cookie`](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Double_Submit_Cookie)
 的方式，保护用户的 API 免于 CSRF 攻击。
 
-在这里我们定义 `GET`, `HEAD` 和 `OPTIONS` 为 `safe-methods`，其他的请求方法为 `unsafe-methods`。
+在此插件运行时，`GET`、`HEAD` 和 `OPTIONS` 会被定义为 `safe-methods`，其他的请求方法则定义为 
`unsafe-methods`。因此 `GET`、`HEAD` 和 `OPTIONS` 方法的调用不会被检查拦截。
 
 ## 属性
 
-| Name             | Type    | Requirement | Default | Valid | Description     
    |
+| 名称             | 类型    | 必选项 | 默认值 | 有效值 | 描述         |
 | ---------------- | ------- | ----------- | ------- | ----- 
|---------------------|
-|   name   |  string |    optional    | `apisix-csrf-token`  |    | 生成的 Cookie 
中的 token 的名字，需要使用这个名字在请求头携带 Cookie 中的内容 |
-| expires |  number | optional | `7200` | | CSRF Cookie 的过期时间（秒）|
-| key | string | required |  |  | 加密 token 的秘钥        |
-
-**注意：当 expires 设置为 0 时插件将忽略检查 Token 是否过期**
+| name   | string | 否    | `apisix-csrf-token`  |    | 生成的 Cookie 中的 Token 
名称，需要使用此名称在请求头携带 Cookie 中的内容。 |
+| expires | number | 否 | `7200` | | CSRF Cookie 的过期时间，单位为秒。当设置为 `0` 时，会忽略 CSRF 
Cookie 过期时间检查。|
+| key | string | 是 |  |  | 加密 Token 的密钥。        |
 
-## 如何启用
+## 启用插件
 
-1. 创建一条路由并启用该插件。
+以下示例展示了如何在指定路由上启用并配置 `csrf` 插件：
 
 ```shell
 curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: 
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -59,38 +65,47 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 
'X-API-KEY: edd1c9f034335
 }'
 ```
 
-这条路由已经开启保护，当你使用 GET 之外的方法访问，请求会被拦截并返回 401 状态码。
+当你使用 `GET` 之外的方法访问被保护的路由时，请求会被拦截并返回 `401` HTTP 状态码。
+
+使用 `GET` 请求 `/hello` 时，在响应中会有一个携带了加密 Token 的 Cookie。Token 字段名称为插件配置中的 `name` 
值，默认为 `apisix-csrf-token`。
+
+:::note
 
-2. 使用 `GET` 请求 `/hello`，在响应中会有一个携带了加密 `token` 的 `Cookie`。Token 字段的名字为插件配置中的 
`name` 值，如果没有配置该值，那么默认值为 `apisix-csrf-token`。
+每一个请求都会返回一个新的 Cookie。
 
-注意：每一个请求都会返回一个新的 Cookie。
+:::
 
-3. 在后续的对该路由的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 token，保证携带 Cookie 
并在请求头部中携带该 token，请求头字段的名称为插件配置中的 `name`。
+在后续对该路由进行的 `unsafe-methods` 请求中，需要从 Cookie 中读取加密的 Token，并在请求头中携带该 
Token。请求头字段的名称为插件属性中的 `name`。
 
 ## 测试插件
 
-直接对该路由发起 `POST` 请求会返回错误：
+启用插件后，使用 `curl` 命令尝试直接对该路由发起 `POST` 请求，会返回 `Unauthorized` 字样的报错提示：
 
 ```shell
 curl -i http://127.0.0.1:9080/hello -X POST
+```
 
+```shell
 HTTP/1.1 401 Unauthorized
 ...
 {"error_msg":"no csrf token in headers"}
 ```
 
-当使用 GET 请求，返回中会有携带 token 的 Cookie：
+当发起 `GET` 请求时，返回结果中会有携带 Token 的 Cookie：
 
 ```shell
 curl -i http://127.0.0.1:9080/hello
+```
 
+```
 HTTP/1.1 200 OK
+...
 Set-Cookie: 
apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon,
 13-Dec-21 09:33:55 GMT
 ```
 
-在请求之前，需要从 Cookie 中读取 token，并在随后的 `unsafe-methods` 请求中的请求头中携带。
+在请求之前，用户需要从 Cookie 中读取 Token，并在后续的 `unsafe-methods` 请求的请求头中携带。
 
-例如，在客户端使用 [js-cookie](https://github.com/js-cookie/js-cookie) 读取 Cookie，使用 
[axios](https://github.com/axios/axios) 发送请求。
+例如，你可以在客户端使用 [js-cookie](https://github.com/js-cookie/js-cookie) 读取 Cookie，使用 
[axios](https://github.com/axios/axios) 发送请求：
 
 ```js
 const token = Cookie.get('apisix-csrf-token');
@@ -100,19 +115,19 @@ const instance = axios.create({
 });
 ```
 
-你还需要确保你的请求携带了 Cookie。
-
-使用 curl 发送请求：
+使用 `curl` 命令发送请求，确保请求中携带了 Cookie 信息，如果返回 `200` HTTP 状态码则表示请求成功：
 
 ```shell
 curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: 
eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
 -b 
'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
+```
 
+```shell
 HTTP/1.1 200 OK
 ```
 
 ## 禁用插件
 
-发送一个更新路由的请求，以停用该插件：
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
 
 ```shell
 curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: 
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -126,5 +141,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 
'X-API-KEY: edd1c9f034335f13
   }
 }'
 ```
-
-CSRF 插件已经被停用。