From 4afc8a7fbf82d4311504abd00f08156a806e5b40 Mon Sep 17 00:00:00 2001 From: homeward <97138894+hf400159@users.noreply.github.com> Date: Thu, 28 Apr 2022 16:03:38 +0800 Subject: [PATCH] docs: fix plugin document's format and contents (#6957) --- docs/zh/latest/plugins/batch-requests.md | 8 ++++---- docs/zh/latest/plugins/grpc-transcode.md | 2 +- docs/zh/latest/plugins/hmac-auth.md | 19 +++++++++++-------- docs/zh/latest/plugins/jwt-auth.md | 2 +- docs/zh/latest/plugins/key-auth.md | 2 +- docs/zh/latest/plugins/openid-connect.md | 4 ++-- 6 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/zh/latest/plugins/batch-requests.md b/docs/zh/latest/plugins/batch-requests.md index 63ba18b91147..067031227ea5 100644 --- a/docs/zh/latest/plugins/batch-requests.md +++ b/docs/zh/latest/plugins/batch-requests.md @@ -42,7 +42,7 @@ description: 本文介绍了关于 Apache APISIX `batch-request` 插件的基本 ## 属性 -无 +无。 ## 接口 @@ -86,7 +86,7 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests \ 该插件会为 `apisix` 创建一个 `/apisix/batch-requests` 的接口，用来处理批量请求。 -### Request +### 请求参数 | 参数名 | 类型 | 必选项 | 默认值 | 描述 | | -------- | --------------------------- | ------ | ------ | -------------------------------- | @@ -107,9 +107,9 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests \ | body | string | 否 | | | HTTP 请求体。 | | ssl_verify | boolean | 否 | false | | 验证 SSL 证书与主机名是否匹配。 | -### 响应参数： +### 响应参数 -返回值是一个 [HttpResponse](#httpresponse) 的 `数组`。 +返回值是一个 [HttpResponse](#httpresponse) 的`数组`。 #### HttpResponse diff --git a/docs/zh/latest/plugins/grpc-transcode.md b/docs/zh/latest/plugins/grpc-transcode.md index b7cb2a821dc5..fb97dd576f8b 100644 --- a/docs/zh/latest/plugins/grpc-transcode.md +++ b/docs/zh/latest/plugins/grpc-transcode.md @@ -1,5 +1,5 @@ --- -title: grpc-web +title: grpc-transcode keywords: - APISIX - Plugin diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index 16beab6d63af..5c26173ddca3 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -112,14 +112,17 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 \ 1. 提取 URL 中的 query 项。 2. 使用 `&` 作为分隔符，将 query 拆分成键值对。 -3. 如果 `encode_uri_param` 为 true 时： - 1. 当该项有 `key` 时，转换公式为 `url_encode(key) + "="`。 - 2. 当该项同时有 `key` 和 `value` 时，转换公式为 `url_encode(key) + "=" + url_encode(value)` 。此处 `value` 可以是空字符串。 - 3. 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的 `canonical_query_string` 。 -4. 如果 `encode_uri_param` 为 false 时： - 1. 当该项只有 `key` 时，转换公式为 `key + "="` 。 - 2. 当该项同时有 `key` 和 `value` 时，转换公式为 `key + "=" + value` 。此处 `value` 可以是空字符串。 - 3. 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 `&` 符号连接起来，生成相应的 `canonical_query_string`。 +3. 如果 `encode_uri_param` 为 `true` 时： + + - 当该项有 `key` 时，转换公式为 `url_encode(key) + "="`。 + - 当该项同时有 `key` 和 `value` 时，转换公式为 `url_encode(key) + "=" + url_encode(value)` 。此处 `value` 可以是空字符串。 + - 将每一项转换后，以 `key` 按照字典顺序（ASCII 码由小到大）排序，并使用 `&` 符号连接起来，生成相应的 `canonical_query_string` 。 + +4. 如果 `encode_uri_param` 为 `false` 时： + + - 当该项只有 `key` 时，转换公式为 `key + "="` 。 + - 当该项同时有 `key` 和 `value` 时，转换公式为 `key + "=" + value` 。此处 `value` 可以是空字符串。 + - 将每一项转换后，以 `key` 按照字典顺序（ASCII 码由小到大）排序，并使用 `&` 符号连接起来，生成相应的 `canonical_query_string`。 > 生成 `signed_headers_string` 的算法如下： diff --git a/docs/zh/latest/plugins/jwt-auth.md b/docs/zh/latest/plugins/jwt-auth.md index f27dbde51d82..cefb574cf3d7 100644 --- a/docs/zh/latest/plugins/jwt-auth.md +++ b/docs/zh/latest/plugins/jwt-auth.md @@ -33,7 +33,7 @@ description: 本文介绍了关于 Apache APISIX `jwt-auth` 插件的基本信 通过 Consumer 将其密匙添加到查询字符串参数、请求头或 `cookie` 中用来验证其请求。 -`jwt-auth` 插件可以与 [HashiCorp Vault](https://www.vaultproject.io/) 集成，用于存储和获取密钥，并从 HashiCorp Vault 的 [encrypted KV engine](https://www.vaultproject.io/docs/secrets/kv)中获取 RSA 密匙对。你可以从下面的 [示例](#与-HashiCorp-Vault-一起使用) 中了解更多信息。 +`jwt-auth` 插件可以与 [HashiCorp Vault](https://www.vaultproject.io/) 集成，用于存储和获取密钥，并从 HashiCorp Vault 的 [encrypted KV engine](https://www.vaultproject.io/docs/secrets/kv)中获取 RSA 密匙对。你可以从下面的[示例](#与-hashicorp-vault-集成使用)中了解更多信息。 ## 属性 diff --git a/docs/zh/latest/plugins/key-auth.md b/docs/zh/latest/plugins/key-auth.md index 1bb44a224a0c..254bc203c188 100644 --- a/docs/zh/latest/plugins/key-auth.md +++ b/docs/zh/latest/plugins/key-auth.md @@ -46,7 +46,7 @@ Router 端： | 名称 | 类型 | 必选项 | 默认值 | 描述 | | ----------------- | ------ | ----- | ------ |------------------------------------------------------------------------------------------------------------- | | header | string | 否 | apikey | 设置我们从哪个 header 获取 key。 | -| query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header` | +| query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header`。 | | hide_credentials | bool | 否 | false | 当设置为 `false` 时将含有认证信息的请求头传递给 Upstream。 | ## 启用插件 diff --git a/docs/zh/latest/plugins/openid-connect.md b/docs/zh/latest/plugins/openid-connect.md index 812b253b577c..16a8f9bfe47d 100644 --- a/docs/zh/latest/plugins/openid-connect.md +++ b/docs/zh/latest/plugins/openid-connect.md @@ -61,9 +61,9 @@ description: 本文介绍了关于 Apache APISIX `openid-connect` 插件的基 1. 可以将**插件**配置为：仅验证预期会出现在请求头中的访问令牌。在这种模式下，没有令牌或带有无效令牌的请求将被拒绝。这需要将 `bearer_only` 属性设置为 `true` 并配置 `introspection_endpoint` 或 `public_key` 属性。这种操作模式可用于服务端之间的通信，在这种模式下，请求者可以合理地获取和管理有效的令牌。 -2. 可以将插件配置为：通过 OIDC 授权对没有有效令牌的请求进行身份验证，其中该插件充当 OIDC 依赖方。在这种情况下，认证成功后，该插件可以获得并管理会话 Cookie 中的访问令牌，包含 Cookie 的后续请求将使用访问令牌。你需要将 `bearer_only` 属性设置为 `false` 才可以使用这种模式。这种操作模式可用于支持以下情况：客户端或请求者是通过 Web 浏览器进行交互的用户。 +2. 可以将**插件**配置为：通过 OIDC 授权对没有有效令牌的请求进行身份验证，其中该插件充当 OIDC 依赖方。在这种情况下，认证成功后，该插件可以获得并管理会话 Cookie 中的访问令牌，包含 Cookie 的后续请求将使用访问令牌。你需要将 `bearer_only` 属性设置为 `false` 才可以使用这种模式。这种操作模式可用于支持以下情况：客户端或请求者是通过 Web 浏览器进行交互的用户。 -3. 插件也可以通过将 `bearer_only` 设置为 `false`，并配置 `introspection_endpoint` 或 `public_key` 属性来支持以上两种场景。在这种情况下，对来自请求头的现有令牌的自省优先于依赖方流程。也就是说，如果一个请求中包含一个无效的令牌，那么该请求将会被拒绝，不会从重定向到 ID 提供者获得一个有效的令牌。 +3. 该插件也可以通过将 `bearer_only` 设置为 `false`，并配置 `introspection_endpoint` 或 `public_key` 属性来支持以上两种场景。在这种情况下，对来自请求头的现有令牌的自省优先于依赖方流程。也就是说，如果一个请求中包含一个无效的令牌，那么该请求将会被拒绝，不会从重定向到 ID 提供者获得一个有效的令牌。 用于验证请求的方法会影响到 header，你可以在将请求发送到上游服务之前对其执行。