yzeng25 commented on code in PR #7064: URL: https://github.com/apache/apisix/pull/7064#discussion_r874652425
########## docs/en/latest/plugins/proxy-control.md: ########## @@ -23,19 +29,23 @@ title: proxy-control ## Description -The `proxy-control` plugin dynamically controls the behavior of Nginx to proxy. +The proxy-control Plugin dynamically controls the behavior of the Nginx proxy. -**This plugin requires APISIX to run on [APISIX-Base](../FAQ.md#how-do-i-build-the-apisix-base-environment?).** +:::info IMPORTANT + +This Plugin requires APISIX to run on APISIX-Base. See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for more info. + +::: ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| request_buffering | boolean | optional | true | | dynamically set the `proxy_request_buffering` directive | +| Name | Type | Required | Default | Description | +| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| request_buffering | boolean | False | true | When set to true, dynamically sets the [proxy_request_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering) directive. | Review Comment: ```suggestion | request_buffering | boolean | False | true | When set to `true`, it dynamically sets the [proxy_request_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering) directive. | ``` ########## docs/en/latest/plugins/client-control.md: ########## @@ -23,20 +29,23 @@ title: client-control ## Description -The `client-control` plugin dynamically controls the behavior of Nginx to -handle the client request. +The `client-control` Plugin can be used to dynamically control the behavior of Nginx to handle a client request. -**This plugin requires APISIX to run on [APISIX-Base](../FAQ.md#how-do-i-build-the-apisix-base-environment?).** +:::info IMPORTANT + +This Plugin requires APISIX to run on APISIX-Base. See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for more info. + +::: ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| max_body_size | integer | optional | | >= 0 | dynamically set the `client_max_body_size` directive | +| Name | Type | Required | Valid values | Description | +| ------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| max_body_size | integer | False | >= 0 | Dynamically set the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | Review Comment: ```suggestion | max_body_size | integer | False | [0,...] | Dynamically set the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | ``` ########## docs/en/latest/plugins/client-control.md: ########## @@ -76,9 +87,7 @@ HTTP/1.1 413 Request Entity Too Large ## Disable Plugin -When you want to disable this plugin, it is very simple, -you can delete the corresponding json configuration in the plugin configuration, -no need to restart the service, it will take effect immediately: +To disable the `client-control` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. Review Comment: ```suggestion To disable the `client-control` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload, and you do not have to restart for this to take effect. ``` ########## docs/en/latest/plugins/request-id.md: ########## @@ -23,20 +29,60 @@ title: request-id ## Description -`request-id` plugin adds a unique ID (UUID) to each request proxied through APISIX. This plugin can be used to track an -API request. The plugin will not add a request id if the `header_name` is already present in the request. +The `request-id` Plugin adds a unique ID to each request proxied through APISIX. + +This Plugin can be used to track API requests. + +:::note + +The Plugin will not add a unique ID if the request already has a header with the configured `header_name`. + +::: ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| ------------------- | ------- | ----------- | -------------- | ----- | -------------------------------------------------------------- | -| header_name | string | optional | "X-Request-Id" | | Request ID header name | -| include_in_response | boolean | optional | true | | Option to include the unique request ID in the response header | -| algorithm | string | optional | "uuid" | ["uuid", "snowflake", "nanoid"] | ID generation algorithm | +| Name | Type | Required | Default | Valid values | Description | +| ------------------- | ------- | -------- | -------------- | ------------------------------- | ---------------------------------------------------------------------- | +| header_name | string | False | "X-Request-Id" | | Header name for the unique request ID. | +| include_in_response | boolean | False | true | | When set to `true`, adds the unique request ID in the response header. | +| algorithm | string | False | "uuid" | ["uuid", "snowflake", "nanoid"] | Algorithm to use for generating the unique request ID. | -## How To Enable +### Using snowflake algorithm to generate unique ID -Create a route and enable the request-id plugin on the route: +To use the snowflake algorithm, you have to enable it first on your configuration file (`conf/config.yaml`): + +```yaml title="conf/config.yaml" +plugin_attr: + request-id: + snowflake: + enable: true + snowflake_epoc: 1609459200000 + data_machine_bits: 12 + sequence_bits: 10 + data_machine_ttl: 30 + data_machine_interval: 10 +``` + +:::warning Review Comment: I don't see "warning" listed on https://docusaurus.io/docs/markdown-features/admonitions, please specify which one you'd like to use. Personally I think `:::caution` should do the work. ########## docs/en/latest/plugins/request-id.md: ########## @@ -23,20 +29,60 @@ title: request-id ## Description -`request-id` plugin adds a unique ID (UUID) to each request proxied through APISIX. This plugin can be used to track an -API request. The plugin will not add a request id if the `header_name` is already present in the request. +The `request-id` Plugin adds a unique ID to each request proxied through APISIX. + +This Plugin can be used to track API requests. + +:::note + +The Plugin will not add a unique ID if the request already has a header with the configured `header_name`. + +::: ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| ------------------- | ------- | ----------- | -------------- | ----- | -------------------------------------------------------------- | -| header_name | string | optional | "X-Request-Id" | | Request ID header name | -| include_in_response | boolean | optional | true | | Option to include the unique request ID in the response header | -| algorithm | string | optional | "uuid" | ["uuid", "snowflake", "nanoid"] | ID generation algorithm | +| Name | Type | Required | Default | Valid values | Description | +| ------------------- | ------- | -------- | -------------- | ------------------------------- | ---------------------------------------------------------------------- | +| header_name | string | False | "X-Request-Id" | | Header name for the unique request ID. | +| include_in_response | boolean | False | true | | When set to `true`, adds the unique request ID in the response header. | +| algorithm | string | False | "uuid" | ["uuid", "snowflake", "nanoid"] | Algorithm to use for generating the unique request ID. | -## How To Enable +### Using snowflake algorithm to generate unique ID -Create a route and enable the request-id plugin on the route: +To use the snowflake algorithm, you have to enable it first on your configuration file (`conf/config.yaml`): + +```yaml title="conf/config.yaml" +plugin_attr: + request-id: + snowflake: + enable: true + snowflake_epoc: 1609459200000 + data_machine_bits: 12 + sequence_bits: 10 + data_machine_ttl: 30 + data_machine_interval: 10 +``` + +:::warning + +Please read this documentation before deciding to use the snowflake algorithm. Once it is configured, you cannot arbitrarily change the configuration. Failure to do so may result in duplicate ID being generated. Review Comment: ```suggestion Please read this documentation before deciding to use the snowflake algorithm. Once it is configured, you cannot arbitrarily change the configuration. Failure to do so may result in duplicate IDs. ``` ########## docs/en/latest/plugins/request-id.md: ########## @@ -23,20 +29,60 @@ title: request-id ## Description -`request-id` plugin adds a unique ID (UUID) to each request proxied through APISIX. This plugin can be used to track an -API request. The plugin will not add a request id if the `header_name` is already present in the request. +The `request-id` Plugin adds a unique ID to each request proxied through APISIX. + +This Plugin can be used to track API requests. + +:::note + +The Plugin will not add a unique ID if the request already has a header with the configured `header_name`. + +::: ## Attributes -| Name | Type | Requirement | Default | Valid | Description | -| ------------------- | ------- | ----------- | -------------- | ----- | -------------------------------------------------------------- | -| header_name | string | optional | "X-Request-Id" | | Request ID header name | -| include_in_response | boolean | optional | true | | Option to include the unique request ID in the response header | -| algorithm | string | optional | "uuid" | ["uuid", "snowflake", "nanoid"] | ID generation algorithm | +| Name | Type | Required | Default | Valid values | Description | +| ------------------- | ------- | -------- | -------------- | ------------------------------- | ---------------------------------------------------------------------- | +| header_name | string | False | "X-Request-Id" | | Header name for the unique request ID. | +| include_in_response | boolean | False | true | | When set to `true`, adds the unique request ID in the response header. | +| algorithm | string | False | "uuid" | ["uuid", "snowflake", "nanoid"] | Algorithm to use for generating the unique request ID. | -## How To Enable +### Using snowflake algorithm to generate unique ID -Create a route and enable the request-id plugin on the route: +To use the snowflake algorithm, you have to enable it first on your configuration file (`conf/config.yaml`): + +```yaml title="conf/config.yaml" +plugin_attr: + request-id: + snowflake: + enable: true + snowflake_epoc: 1609459200000 + data_machine_bits: 12 + sequence_bits: 10 + data_machine_ttl: 30 + data_machine_interval: 10 +``` + +:::warning Review Comment: If you decide to stick with "waring", you can also do a trick like `:::caution Warning`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
