You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2021/07/19 02:25:15 UTC
[apisix] branch master updated: docs: improve/sync zh and en docs
of the admin-api (#4615)
This is an automated email from the ASF dual-hosted git repository.
spacewander 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 df3ed8b docs: improve/sync zh and en docs of the admin-api (#4615)
df3ed8b is described below
commit df3ed8bcf4c3903d5788bd9fe3f85a7ed5c47db4
Author: okaybase <75...@users.noreply.github.com>
AuthorDate: Mon Jul 19 10:25:04 2021 +0800
docs: improve/sync zh and en docs of the admin-api (#4615)
---
docs/en/latest/admin-api.md | 56 ++++++++++++++++++++++-----------------------
docs/zh/latest/admin-api.md | 6 ++---
2 files changed, 31 insertions(+), 31 deletions(-)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index 8cfeea2..95612db 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -73,8 +73,8 @@ Note: When the `Admin API` is enabled, it will occupy the API prefixed with `/ap
| Parameter | Required | Type | Description [...]
| ---------------- | ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ [...]
-| name | False | Auxiliary | Identifies route names. [...]
-| desc | False | Auxiliary | route description, usage scenarios, and more. [...]
+| name | False | Auxiliary | Identifies route names. [...]
+| desc | False | Auxiliary | route description, usage scenarios, and more. [...]
| uri | True, can't be used with `uris` | Match Rules | In addition to full matching such as `/foo/bar`、`/foo/gloo`, using different [Router](architecture-design/router.md) allows more advanced matching, see [Router](architecture-design/router.md) for more. [...]
| uris | True, can't be used with `uri` | Match Rules | The `uri` in the form of a non-empty list means that multiple different uris are allowed, and match any one of them. [...]
| host | False, can't be used with `hosts` | Match Rules | Currently requesting a domain name, such as `foo.com`; PAN domain names such as `*.foo.com` are also supported. [...]
@@ -319,8 +319,8 @@ Return response from etcd currently.
| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
| upstream | False | Upstream | Enabled Upstream configuration, see [Upstream](architecture-design/upstream.md) for more | |
| upstream_id | False | Upstream | Enabled upstream id, see [Upstream](architecture-design/upstream.md) for more | |
-| name | False | Auxiliary | Identifies service names. | customer-xxxx |
-| desc | False | Auxiliary | service usage scenarios, and more. | customer xxxx |
+| name | False | Auxiliary | Identifies service names. | service-xxxx |
+| desc | False | Auxiliary | service usage scenarios, and more. | service xxxx |
| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
| enable_websocket | False | Auxiliary | enable `websocket`(boolean), default `false`. | |
| create_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
@@ -536,31 +536,31 @@ Return response from etcd currently.
In addition to the basic complex equalization algorithm selection, APISIX's Upstream also supports logic for upstream passive health check and retry, see the table below.
-|Name |Optional|Description|
-|----------------|--------|-----------|
-|type |required|the balancer algorithm|
-|nodes |required, can't be used with `service_name` |Hash table or array. If it is a hash table, the key of the internal element is the upstream machine address list, the format is `Address + (optional) Port`, where the address part can be IP or domain name, such as `192.168.1.100:80`, `foo.com:80`, etc. The value is the weight of node. If it is an array, each item is a hash table with key `host`/`weight` and optional `port`/`priority`. The `nodes` can be empty, which means it [...]
-|service_name |required, can't be used with `nodes` |the name of service used in the service discovery, see [discovery](discovery.md) for more details|
-|discovery_type |required, if `service_name` is used | the type of service discovery, see [discovery](discovery.md) for more details|
-|hash_on |optional|This option is only valid if the `type` is `chash`. Supported types `vars`(Nginx variables), `header`(custom header), `cookie`, `consumer`, the default value is `vars`.|
-|key |optional|This option is only valid if the `type` is `chash`. Find the corresponding node `id` according to `hash_on` and `key`. When `hash_on` is set as `vars`, `key` is the required parameter, for now, it support nginx built-in variables like `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`, `arg_***` is arguments in the request line, [Nginx variables list](http://nginx.org/en/docs/varindex.html). When `hash_ [...]
-|checks |optional|Configure the parameters of the health check. For details, refer to [health-check](health-check.md).|
-|retries |optional|Pass the request to the next upstream using the underlying Nginx retry mechanism, the retry mechanism is enabled by default and set the number of retries according to the number of available backend nodes. If `retries` option is explicitly set, it will override the default value. `0` means disable retry mechanism.|
-|retry_timeout |optional|Configure a number to limit the amount of seconds that retries can be continued, and do not continue retries if the previous request and retry requests have taken too long. `0` means disable retry timeout mechanism.|
-|timeout |optional| Set the timeout for connecting, sending and receiving messages. |
-|name |optional|Identifies upstream names|
-|desc |optional|upstream usage scenarios, and more.|
-|pass_host |optional| `host` option when the request is sent to the upstream, can be one of [`pass`, `node`, `rewrite`], the default option is `pass`. `pass`: Pass the client's host transparently to the upstream; `node`: Use the host configured in the node of `upstream`; `rewrite`: Use the value of the configuration `upstream_host`.|
-|upstream_host |optional|Specify the host of the upstream request. This option is only valid if the `pass_host` is `rewrite`.|
-|scheme |optional |The scheme used when talk with the upstream. The value is one of ['http', 'https', 'grpc', 'grpcs'], default to 'http'.|
+|Name |Optional|Description|Example|
+|----------------|--------|-----------|-----------|
+|type |required|the balancer algorithm||
+|nodes |required, can't be used with `service_name` |Hash table or array. If it is a hash table, the key of the internal element is the upstream machine address list, the format is `Address + (optional) Port`, where the address part can be IP or domain name, such as `192.168.1.100:80`, `foo.com:80`, etc. The value is the weight of node. If it is an array, each item is a hash table with key `host`/`weight` and optional `port`/`priority`. The `nodes` can be empty, which means it [...]
+|service_name |required, can't be used with `nodes` |the name of service used in the service discovery, see [discovery](discovery.md) for more details|`a-bootiful-client`|
+|discovery_type |required, if `service_name` is used | the type of service discovery, see [discovery](discovery.md) for more details|`eureka`|
+|hash_on |optional|This option is only valid if the `type` is `chash`. Supported types `vars`(Nginx variables), `header`(custom header), `cookie`, `consumer`, the default value is `vars`.||
+|key |optional|This option is only valid if the `type` is `chash`. Find the corresponding node `id` according to `hash_on` and `key`. When `hash_on` is set as `vars`, `key` is the required parameter, for now, it support nginx built-in variables like `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`, `arg_***` is arguments in the request line, [Nginx variables list](http://nginx.org/en/docs/varindex.html). When `hash_ [...]
+|checks |optional|Configure the parameters of the health check. For details, refer to [health-check](health-check.md).||
+|retries |optional|Pass the request to the next upstream using the underlying Nginx retry mechanism, the retry mechanism is enabled by default and set the number of retries according to the number of available backend nodes. If `retries` option is explicitly set, it will override the default value. `0` means disable retry mechanism.||
+|retry_timeout |optional|Configure a number to limit the amount of seconds that retries can be continued, and do not continue retries if the previous request and retry requests have taken too long. `0` means disable retry timeout mechanism.||
+|timeout |optional| Set the timeout for connecting, sending and receiving messages. ||
+|name |optional|Identifies upstream names||
+|desc |optional|upstream usage scenarios, and more.||
+|pass_host |optional| `host` option when the request is sent to the upstream, can be one of [`pass`, `node`, `rewrite`], the default option is `pass`. `pass`: Pass the client's host transparently to the upstream; `node`: Use the host configured in the node of `upstream`; `rewrite`: Use the value of the configuration `upstream_host`.||
+|upstream_host |optional|Specify the host of the upstream request. This option is only valid if the `pass_host` is `rewrite`.||
+|scheme |optional |The scheme used when talk with the upstream. The value is one of ['http', 'https', 'grpc', 'grpcs'], default to 'http'.||
|labels |optional |Key/value pairs to specify attributes|{"version":"v2","build":"16","env":"production"}|
-|create_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|
-|update_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|
-|tls.client_cert |optional| Set the client certificate when connecting to TLS upstream, see below for more details|
-|tls.client_key |optional| Set the client priviate key when connecting to TLS upstream, see below for more details|
-|keepalive_pool.size |optional| Set `keepalive` directive dynamically, see below for more details|
-|keepalive_pool.idle_timeout |optional| Set `keepalive_timeout` directive dynamically, see below for more details|
-|keepalive_pool.requests |optional| Set `keepalive_requests` directive dynamically, see below for more details|
+|create_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|1602883670|
+|update_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|1602883670|
+|tls.client_cert |optional| Set the client certificate when connecting to TLS upstream, see below for more details||
+|tls.client_key |optional| Set the client priviate key when connecting to TLS upstream, see below for more details||
+|keepalive_pool.size |optional| Set `keepalive` directive dynamically, see below for more details||
+|keepalive_pool.idle_timeout |optional| Set `keepalive_timeout` directive dynamically, see below for more details||
+|keepalive_pool.requests |optional| Set `keepalive_requests` directive dynamically, see below for more details||
`type` can be one of:
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 3b359cc..de34148 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -83,7 +83,7 @@ Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递
| service_id | 可选 | Service | 绑定的 Service 配置，详见 [Service](architecture-design/service.md) | |
| plugin_config_id | 可选，无法跟 script 一起配置 | Plugin | 绑定的 Plugin config 配置，详见 [Plugin config](architecture-design/plugin-config.md) | |
| name | 可选 | 辅助 | 标识路由名称 | route-xxxx |
-| desc | 可选 | 辅助 | 标识描述、使用场景等。 | 客户 xxxx |
+| desc | 可选 | 辅助 | 标识描述、使用场景等。 | 路由 xxxx |
| host | 可选，不能与 `hosts` 一起使用 | 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。 | "foo.com" |
| hosts | 可选，不能与 `host` 一起使用 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。 | {"foo.com", "\*.bar.com"} |
| remote_addr | 可选，不能与 `remote_addrs` 一起使用 | 匹配规则 | 客户端请求 IP 地址: `192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`, `fe80::1/64` 等。 | "192.168.1.0/24" |
@@ -321,7 +321,7 @@ HTTP/1.1 200 OK
| plugins | 可选 | Plugin | 详见 [Plugin](architecture-design/plugin.md) | |
| upstream | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 Upstream 配置，详见 [Upstream](architecture-design/upstream.md) | |
| upstream_id | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 upstream id，详见 [Upstream](architecture-design/upstream.md) | |
-| name | 可选 | 辅助 | 标识服务名称。 | |
+| name | 可选 | 辅助 | 标识服务名称。 | |
| desc | 可选 | 辅助 | 服务描述、使用场景等。 | |
| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`. | |
@@ -544,7 +544,7 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
| 名字 | 可选项 | 类型 | 说明 | 示例 |
| -------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| type | 必需 | 枚举 | | 负载均衡算法 | |
+| type | 必需 | 枚举 | 负载均衡算法 | | |
| nodes | 必需，不能和 `service_name` 一起用 | Node | 哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为`地址 + （可选的）端口`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 `host`、`weight` 以及可选的 `port`、`priority`。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。 | `192.168.1.100:80` |
| service_name | 必需，不能和 `nodes` 一起用 | string | 服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md) | `a-bootiful-client` |
| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见[集成服务发现注册中心](./discovery.md) | `eureka` |