Merge pull request #9082 from HJianBo/update-api-docs

chore(i18n): enrich HTTP API desc

apps/emqx_authn/src/emqx_authn_api.erl

@@ -34,7 +34,7 @@
 % Swagger
 
 -define(API_TAGS_GLOBAL, [<<"Authentication">>]).
--define(API_TAGS_SINGLE, [<<"Listener authentication">>]).
+-define(API_TAGS_SINGLE, [<<"Listener Authentication">>]).
 
 -export([
     api_spec/0,

apps/emqx_authn/src/emqx_authn_user_import_api.erl

@@ -30,7 +30,7 @@
 
 % Swagger
 -define(API_TAGS_GLOBAL, [<<"Authentication">>]).
--define(API_TAGS_SINGLE, [<<"Listener authentication">>]).
+-define(API_TAGS_SINGLE, [<<"Listener Authentication">>]).
 
 -export([
     api_spec/0,

apps/emqx_auto_subscribe/src/emqx_auto_subscribe.app.src

@@ -1,7 +1,7 @@
 %% -*- mode: erlang -*-
 {application, emqx_auto_subscribe, [
     {description, "An OTP application"},
-    {vsn, "0.1.1"},
+    {vsn, "0.1.2"},
     {registered, []},
     {mod, {emqx_auto_subscribe_app, []}},
     {applications, [

apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl

@@ -44,14 +44,14 @@ schema("/mqtt/auto_subscribe") ->
         'operationId' => auto_subscribe,
         get => #{
             description => ?DESC(list_auto_subscribe_api),
-            tags => [<<"Auto subscribe">>],
+            tags => [<<"Auto Subscribe">>],
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe")
             }
         },
         put => #{
             description => ?DESC(update_auto_subscribe_api),
-            tags => [<<"Auto subscribe">>],
+            tags => [<<"Auto Subscribe">>],
             'requestBody' => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),

apps/emqx_dashboard/src/emqx_dashboard_error_code_api.erl

@@ -51,7 +51,7 @@ schema("/error_codes") ->
         get => #{
             security => [],
             description => <<"API Error Codes">>,
-            tags => [<<"Error codes">>],
+            tags => [<<"Error Codes">>],
             responses => #{
                 200 => hoconsc:array(hoconsc:ref(?MODULE, error_code))
             }
@@ -63,7 +63,7 @@ schema("/error_codes/:code") ->
         get => #{
             security => [],
             description => <<"API Error Codes">>,
-            tags => [<<"Error codes">>],
+            tags => [<<"Error Codes">>],
             parameters => [
                 {code,
                     hoconsc:mk(hoconsc:enum(emqx_dashboard_error_code:all()), #{

apps/emqx_exhook/src/emqx_exhook.app.src

@@ -1,7 +1,7 @@
 %% -*- mode: erlang -*-
 {application, emqx_exhook, [
     {description, "EMQX Extension for Hook"},
-    {vsn, "5.0.4"},
+    {vsn, "5.0.5"},
     {modules, []},
     {registered, []},
     {mod, {emqx_exhook_app, []}},

apps/emqx_exhook/src/emqx_exhook_api.erl

@@ -41,7 +41,7 @@
 -import(hoconsc, [mk/1, mk/2, ref/1, enum/1, array/1, map/2]).
 -import(emqx_dashboard_swagger, [schema_with_example/2, error_codes/2]).
 
--define(TAGS, [<<"exhooks">>]).
+-define(TAGS, [<<"ExHook">>]).
 -define(NOT_FOURD, 'NOT_FOUND').
 -define(BAD_REQUEST, 'BAD_REQUEST').
 -define(BAD_RPC, 'BAD_RPC').

apps/emqx_gateway/i18n/emqx_gateway_api_authn_i18n.conf

@@ -2,70 +2,76 @@ emqx_gateway_api_authn {
 
     get_authn {
         desc {
-            en: """Get the gateway authentication"""
-            zh: """获取指定网关认证器"""
+            en: """Gets the configuration of the specified gateway authenticator.</br>
+Returns 404 when gateway or authentication is not enabled."""
+            zh: """获取指定网关认证器的配置
+当网关或认证未启用时，返回 404。"""
         }
     }
 
     update_authn {
         desc {
-            en: """Update authentication for the gateway"""
-            zh: """更新网关认证器"""
+            en: """Update the configuration of the specified gateway authenticator, or disable the authenticator."""
+            zh: """更新指定网关认证器的配置，或停用认证器。"""
         }
     }
 
     add_authn {
         desc {
-            en: """Add authentication for the gateway"""
-            zh: """为指定网关新增认证器"""
+            en: """Enables the authenticator for client authentication for the specified gateway. <\br>
+When the authenticator is not configured or turned off, all client connections are assumed to be allowed. <\br>
+Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT."""
+            zh: """为指定网关开启认证器实现客户端认证的功能。<\br>
+当未配置认证器或关闭认证器时，则认为允许所有客户端的连接。<\br>
+注：在网关中仅支持添加一个认证器，而不是像 MQTT 一样允许配置多个认证器构成认证链。"""
         }
     }
 
     delete_authn {
         desc {
-            en: """Remove the gateway authentication"""
-            zh: """删除指定网关的认证器"""
+            en: """Delete the authenticator of the specified gateway."""
+            zh: """删除指定网关的认证器。"""
         }
     }
 
     list_users {
         desc {
-            en: """Get the users for the authentication"""
+            en: """Get the users for the authenticator (only supported by <code>built_in_database</code>)."""
             zh: """获取用户列表（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     add_user {
         desc {
-            en: """Add user for the authentication"""
+            en: """Add user for the authenticator (only supports built_in_database)."""
             zh: """添加用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     get_user {
         desc {
-            en: """Get user info from the gateway authentication"""
+            en: """Get user info from the gateway authenticator (only supports built_in_database)"""
             zh: """获取用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     update_user {
         desc {
-            en: """Update the user info for the gateway authentication"""
+            en: """Update the user info for the gateway authenticator (only supports built_in_database)"""
             zh: """更新用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     delete_user {
         desc {
-            en: """Delete the user for the gateway authentication"""
+            en: """Delete the user for the gateway authenticator (only supports built_in_database)"""
             zh: """删除用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     import_users {
         desc {
-            en: """Import users into the gateway authentication"""
+            en: """Import users into the gateway authenticator (only supports built_in_database)"""
             zh: """导入用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
@@ -79,8 +85,8 @@ emqx_gateway_api_authn {
 
     like_user_id {
         desc {
-            en: """Fuzzy search by user_id (username or clientid)"""
-            zh: """用户 ID （username 或 clientid）模糊搜索"""
+            en: """Fuzzy search using user ID (username or clientid), only supports search by substring."""
+            zh: """使用用户 ID （username 或 clientid）模糊搜索，仅支持按子串的方式进行搜索。"""
         }
     }
 
@@ -90,5 +96,4 @@ emqx_gateway_api_authn {
             zh: """是否是超级用户"""
         }
     }
-
 }

apps/emqx_gateway/i18n/emqx_gateway_api_i18n.conf

@@ -2,15 +2,17 @@ emqx_gateway_api {
 
     list_gateway {
         desc {
-            en: """Get gateway list"""
-            zh: """获取网关列表"""
+            en: """This API returns an overview info for the specified or all gateways.
+including current running status, number of connections, listener status, etc."""
+            zh: """该接口会返回指定或所有网关的概览状态，
+包括当前状态、连接数、监听器状态等。"""
         }
     }
 
     enable_gateway {
         desc {
-            en: """Enable a gateway"""
-            zh: """启用某网关"""
+            en: """Enable a gateway by confs."""
+            zh: """使用配置启动某一网关。"""
         }
     }
 
@@ -23,15 +25,17 @@ emqx_gateway_api {
 
     delete_gateway {
         desc {
-            en: """Delete/Unload the gateway"""
-            zh: """删除/禁用某网关"""
+            en: """Unload the specified gateway"""
+            zh: """停用指定网关"""
         }
     }
 
     update_gateway {
         desc {
-            en: """Update the gateway configurations/status"""
-            zh: """更新网关配置或启用状态"""
+            en: """Update the gateway basic configurations and running status.</br>
+Note: The Authentication and Listener configurations should be updated by other special APIs. """
+            zh: """更新指定网关的基础配置、和启用的状态。</br>
+注：认证、和监听器的配置更新需参考对应的 API 接口。"""
         }
     }
 
@@ -42,13 +46,33 @@ emqx_gateway_api {
         }
     }
 
+    gateway_name_in_qs {
+        desc {
+            en: """Gateway Name.</br>
+It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
+"""
+            zh: """网关名称.</br>
+可取值为 `stomp`、`mqttsn`、`coap`、`lwm2m`、`exproto`
+"""
+        }
+    }
+
     gateway_status {
         desc {
-            en: """Gateway Status"""
+            en: """Gateway status"""
             zh: """网关启用状态"""
         }
     }
 
+    gateway_status_in_qs {
+        desc {
+            en: """Filter gateways by status.</br>
+It is enum with `running`, `stopped`, `unloaded`"""
+            zh: """通过网关状态筛选</br>
+可选值为 `running`、`stopped`、`unloaded`"""
+        }
+    }
+
     gateway_created_at {
         desc {
             en: """The Gateway created datetime"""