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 940e385b1 docs: refactor cors.md (#7398)
940e385b1 is described below
commit 940e385b18f1949466d61d54e406858ede5cbb65
Author: Yuedong Wu <[email protected]>
AuthorDate: Fri Jul 8 16:23:46 2022 +0800
docs: refactor cors.md (#7398)
---
docs/en/latest/plugins/cors.md | 5 ++--
docs/zh/latest/plugins/cors.md | 64 +++++++++++++++++++++++++-----------------
2 files changed, 41 insertions(+), 28 deletions(-)
diff --git a/docs/en/latest/plugins/cors.md b/docs/en/latest/plugins/cors.md
index 2205805da..913f58668 100644
--- a/docs/en/latest/plugins/cors.md
+++ b/docs/en/latest/plugins/cors.md
@@ -2,7 +2,7 @@
title: cors
keywords:
- APISIX
- - Plugin
+ - API Gateway
- CORS
description: This document contains information about the Apache APISIX cors
Plugin.
---
@@ -45,7 +45,8 @@ The `cors` Plugins lets you enable
[CORS](https://developer.mozilla.org/en-US/do
:::info IMPORTANT
-The `allow_credential` attribute is sensitive and must be used carefully. If
set to `true` the default value `*` of the other attributes will be invalid and
they should be specified explicitly. When using `**` you are vulnerable to
security risks like CSRF. Make sure that this meets your security levels before
using it.
+1. The `allow_credential` attribute is sensitive and must be used carefully.
If set to `true` the default value `*` of the other attributes will be invalid
and they should be specified explicitly.
+2. When using `**` you are vulnerable to security risks like CSRF. Make sure
that this meets your security levels before using it.
:::
diff --git a/docs/zh/latest/plugins/cors.md b/docs/zh/latest/plugins/cors.md
index 0ffa98981..7bda1ac77 100644
--- a/docs/zh/latest/plugins/cors.md
+++ b/docs/zh/latest/plugins/cors.md
@@ -1,5 +1,10 @@
---
title: cors
+keywords:
+ - APISIX
+ - API Gateway
+ - CORS
+description: 本文介绍了 Apache APISIX cors 插件的基本信息及使用方法。
---
<!--
@@ -23,35 +28,39 @@ title: cors
## 描述
-`cors` 插件可以让你为服务端启用
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。
+`cors` 插件可以让你轻松地为服务端启用
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin
Resource Sharing，跨域资源共享）的返回头。
## 属性
-| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述
|
-| ---------------- | ------- | ------ | ------ | ------ |
------------------------------------------------------------ |
-| allow_origins | string | 可选 | "*" | | 允许跨域访问的
Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,`
分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了
`allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 |
-| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如:
`GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin
均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 |
-| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS
规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有
Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header
都通过，但请注意这样存在安全隐患。 |
-| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS
规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意
Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 |
-| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS
结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考
[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。
|
-| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如
Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 |
-| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的
Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 |
-| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的
`allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE":
"https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问
|
-
-> **提示**
->
-> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。
-> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| ---------------- | ------- | ------ | ------ |
------------------------------------------------------------ |
+| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式为
`scheme://host:port`，示例如 `https://somedomain.com:8081`。如果你有多个 Origin，请使用 `,`
分隔。当 `allow_credential` 为 `false` 时，可以使用 `*` 来表示允许所有 Origin 通过。你也可以在启用了
`allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 |
+| allow_methods | string | 否 | "*" | 允许跨域访问的 Method，比如：`GET`，`POST`
等。如果你有多个 Method，请使用 `,` 分割。当 `allow_credential` 为 `false` 时，可以使用 `*` 来表示允许所有
Method 通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 |
+| allow_headers | string | 否 | "*" | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的
Header。如果你有多个 Header，请使用 `,` 分割。当 `allow_credential` 为 `false` 时，可以使用 `*`
来表示允许所有 Header 通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header
都通过，但请注意这样存在安全隐患。 |
+| expose_headers | string | 否 | "*" | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的
Header。如果你有多个 Header，请使用 `,` 分割。当 `allow_credential` 为 `false` 时，可以使用 `*`
来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意
Header，但请注意这样存在安全隐患。 |
+| max_age | integer | 否 | 5 | 浏览器缓存 CORS
结果的最大时间，单位为秒。在这个时间范围内，浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考
[Access-Control-Max-Age -
MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#directives)。
|
+| allow_credential | boolean | 否 | false | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据
CORS 规范，如果设置该选项为 `true`，那么将不能在其他属性中使用 `*`。 |
+| allow_origins_by_regex | array | 否 | nil | 使用正则表达式数组来匹配允许跨域访问的 Origin，如
`[".*\.test.com"]` 可以匹配任何 `test.com` 的子域名 `*`。 |
+| allow_origins_by_metadata | array | 否 | nil | 通过引用插件元数据的
`allow_origins` 配置允许跨域访问的 Origin。比如当插件元数据为 `"allow_origins": {"EXAMPLE":
"https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com`
的访问。 |
+
+:::info IMPORTANT
+
+1. `allow_credential` 是一个很敏感的选项，请谨慎开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。
+2. 在使用 `**` 时，需要清楚该参数引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。
+
+:::
## 元数据
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ----------- | ------ | ------ | ----- | ----- | ------------------
|
-| allow_origins | object | 可选 | | | 定义允许跨域访问的 Origin；它的键为
`allow_origins_by_metadata` 使用的引用键， 值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同 |
+| 名称 | 类型 | 必选项 | 描述 |
+| ----------- | ------ | ------ | ------------------ |
+| allow_origins | object | 否 | 定义允许跨域访问的 Origin；它的键为
`allow_origins_by_metadata` 使用的引用键，值则为允许跨域访问的 Origin，其语义与属性中的 `allow_origins`
相同。 |
-## 如何启用
+## 启用插件
-创建 `Route` 或 `Service` 对象，并配置 `cors` 插件。
+你可以在路由或服务上启用 `cors` 插件。
+
+你可以通过如下命令在指定路由上启用 `cors` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -71,10 +80,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
## 测试插件
-请求下接口，发现接口已经返回了 `CORS` 相关的 header，代表插件生效
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
```shell
curl http://127.0.0.1:9080/hello -v
+```
+
+如果返回结果中出现 CORS 相关的 header，则代表插件生效：
+
+```shell
...
< Server: APISIX web server
< Access-Control-Allow-Origin: *
@@ -87,10 +101,10 @@ curl http://127.0.0.1:9080/hello -v
## 禁用插件
-当你想去掉 `cors` 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `cors` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {},
@@ -102,5 +116,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}'
```
-
-现在就已经移除了 `cors` 插件了。其他插件的开启和移除也是同样的方法。
