Merge remote-tracking branch 'zibo/chore/api-desc' into update-api-docs

apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf

@@ -2,78 +2,82 @@ emqx_mgmt_api_alarms {
 
     list_alarms_api {
         desc {
-            en: """List alarms"""
+            en: """List currently activated alarms or historical alarms, determined by query parameters."""
-            zh: """列出告警，获取告警列表"""
+            zh: """列出当前激活的告警或历史告警，由查询参数决定。"""
         }
     }
 
     delete_alarms_api {
         desc {
-            en: """Remove all deactivated alarms"""
+            en: """Remove all historical alarms."""
-            zh: """删除所有历史告警（非活跃告警）"""
+            zh: """删除所有历史告警。"""
         }
     }
 
     delete_alarms_api_response204 {
         desc {
-            en: """Remove all deactivated alarms ok"""
+            en: """Historical alarms have been cleared successfully."""
-            zh: """删除所有历史告警（非活跃告警）成功"""
+            zh: """历史告警已成功清除。"""
         }
     }
 
     get_alarms_qs_activated {
         desc {
-            en: """Activate alarms, or deactivate alarms. Default is false"""
+            en: """It is used to specify the alarm type of the query. 
-            zh: """活跃中的告警，或历史告警（非活跃告警），默认为 false"""
+When true, it returns the currently activated alarm, 
+and when it is false, it returns the historical alarm. 
+The default is false."""
+            zh: """用于指定查询的告警类型，
+为 true 时返回当前激活的告警，为 false 时返回历史告警，默认为 false。"""
         }
     }
 
     node {
         desc {
-            en: """Alarm in node"""
+            en: """The name of the node that triggered this alarm."""
-            zh: """告警节点名称"""
+            zh: """触发此告警的节点名称。"""
         }
     }
 
     name {
         desc {
-            en: """Alarm name"""
+            en: """Alarm name, used to distinguish different alarms."""
-            zh: """告警名称"""
+            zh: """告警名称，用于区分不同的告警。"""
         }
     }
 
     message {
         desc {
-            en: """Alarm readable information"""
+            en: """Alarm message, which describes the alarm content in a human-readable format."""
-            zh: """告警信息"""
+            zh: """告警消息，以人类可读的方式描述告警内容。"""
         }
     }
 
     details {
         desc {
-            en: """Alarm details information"""
+            en: """Alarm details, provides more alarm information, mainly for program processing."""
-            zh: """告警详细信息"""
+            zh: """告警详情，提供了更多的告警信息，主要提供给程序处理。"""
         }
     }
 
     duration {
         desc {
-            en: """Alarms duration time; UNIX time stamp, millisecond"""
+            en: """Indicates how long the alarm has lasted, in milliseconds."""
-            zh: """告警持续时间，单位：毫秒"""
+            zh: """表明告警已经持续了多久，单位：毫秒。"""
         }
     }
 
     activate_at {
         desc {
-            en: """Alarms activate time, RFC 3339"""
+            en: """Alarm start time, using rfc3339 standard time format."""
-            zh: """告警开始时间，使用 rfc3339 标准时间格式"""
+            zh: """告警开始时间，使用 rfc3339 标准时间格式。"""
         }
     }
 
     deactivate_at {
         desc {
-            en: """Alarms deactivate time, RFC 3339"""
+            en: """Alarm end time, using rfc3339 standard time format."""
-            zh: """告警结束时间，使用 rfc3339 标准时间格式"""
+            zh: """告警结束时间，使用 rfc3339 标准时间格式。"""
         }
     }
 

apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf

@@ -2,112 +2,97 @@ emqx_mgmt_api_banned {
 
     list_banned_api {
         desc {
-            en: """List banned."""
+            en: """List all currently banned client IDs, usernames and IP addresses."""
-            zh: """列出黑名单"""
+            zh: """列出目前所有被封禁的客户端 ID、用户名和 IP 地址。"""
-        }
-        label {
-            en: """List Banned"""
-            zh: """列出黑名单"""
         }
     }
 
     create_banned_api {
         desc {
-            en: """Create banned."""
+            en: """Add a client ID, username or IP address to the blacklist."""
-            zh: """创建黑名单"""
+            zh: """添加一个客户端 ID、用户名或者 IP 地址到黑名单。"""
         }
     }
 
     create_banned_api_response400 {
         desc {
-            en: """Banned already existed, or bad args."""
+            en: """Bad request, possibly due to wrong parameters or the existence of a banned object."""
-            zh: """黑名单已存在，或参数格式有错误"""
+            zh: """错误的请求，可能是参数错误或封禁对象已存在等原因。"""
         }
     }
 
     delete_banned_api {
         desc {
-            en: """Delete banned"""
+            en: """Remove a client ID, username or IP address from the blacklist."""
-            zh: """删除黑名单"""
+            zh: """将一个客户端 ID、用户名或者 IP 地址从黑名单中删除。"""
         }
     }
 
     delete_banned_api_response404 {
         desc {
-            en: """Banned not found. May be the banned time has been exceeded"""
+            en: """The banned object was not found in the blacklist."""
-            zh: """黑名单未找到，可能为已经超期失效"""
+            zh: """未在黑名单中找到该封禁对象。"""
-        }
-    }
-
-    create_banned {
-        desc {
-            en: """List banned."""
-            zh: """列出黑名单"""
-        }
-        label {
-            en: """List Banned"""
-            zh: """列出黑名单"""
         }
     }
 
     as {
         desc {
-            en: """Banned type clientid, username, peerhost"""
+            en: """Ban method, which can be client ID, username or IP address."""
-            zh: """黑名单类型，可选 clientid、username、peerhost"""
+            zh: """封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。"""
         }
         label {
-            en: """Banned Type"""
+            en: """Ban Method"""
-            zh: """黑名单类型"""
+            zh: """封禁方式"""
         }
     }
     who {
         desc {
-            en: """Client info as banned type"""
+            en: """Ban object, specific client ID, username or IP address."""
-            zh: """设备信息"""
+            zh: """封禁对象，具体的客户端 ID、用户名或者 IP 地址。"""
         }
         label {
-            en: """Banned Info"""
+            en: """Ban Object"""
-            zh: """黑名单信息"""
+            zh: """封禁对象"""
         }
     }
     by {
         desc {
-            en: """Commander"""
+            en: """Initiator of the ban."""
-            zh: """黑名单创建者"""
+            zh: """封禁的发起者。"""
         }
         label {
-            en: """Commander"""
+            en: """Ban Initiator"""
-            zh: """黑名单创建者"""
+            zh: """封禁发起者"""
         }
     }
     reason {
         desc {
-            en: """Banned reason"""
+            en: """Banned reason, record the reason why the current object was banned."""
-            zh: """黑名单创建原因"""
+            zh: """封禁原因，记录当前对象被封禁的原因。"""
         }
         label {
-            en: """Reason"""
+            en: """Banned Reason"""
-            zh: """原因"""
+            zh: """封禁原因"""
         }
     }
     at {
         desc {
-            en: """Create banned time, rfc3339, now if not specified"""
+            en: """The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated."""
-            zh: """黑名单创建时间，默认为当前"""
+            zh: """封禁的起始时间，格式为 rfc3339，默认为发起操作的时间。"""
         }
         label {
-            en: """Create banned time"""
+            en: """Ban Time"""
-            zh: """黑名单创建时间"""
+            zh: """封禁时间"""
         }
     }
     until {
         desc {
-            en: """Cancel banned time, rfc3339, now + 5 minute if not specified"""
+            en: """The end time of the ban, the formula is rfc3339, the default is the time when the operation was initiated + 5 minutes."""
-            zh: """黑名单结束时间，默认为创建时间 + 5 分钟"""
+            zh: """封禁的结束时间，式为 rfc3339，默认为发起操作的时间 + 5 分钟。"""
         }
         label {
-            en: """Cancel banned time"""
+            en: """Ban End Time"""
-            zh: """黑名单结束时间"""
+            zh: """封禁结束时间"""
         }
     }
 }

apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf

@@ -1,9 +1,23 @@
 emqx_statsd_schema {
 
+  get_statsd_config_api {
+    desc {
+      en: """List the configuration of StatsD metrics collection and push service."""
+      zh: """列出 StatsD 指标采集和推送服务的的配置。"""
+    }
+  }
+
+  update_statsd_config_api {
+    desc {
+      en: """Update the configuration of StatsD metrics collection and push service."""
+      zh: """更新 StatsD 指标采集和推送服务的配置。"""
+    }
+  }
+
   statsd {
     desc {
-      en: """Settings for reporting metrics to StatsD"""
+      en: """StatsD metrics collection and push configuration."""
-      zh: """StatsD 监控数据推送"""
+      zh: """StatsD 指标采集与推送配置。"""
     }
     label {
       en: """StatsD"""
@@ -13,29 +27,29 @@ emqx_statsd_schema {
 
   server {
     desc {
-      en: """URL of StatsD server"""
+      en: """StatsD server address."""
-      zh: """StatsD 服务器地址"""
+      zh: """StatsD 服务器地址。"""
     }
   }
 
   sample_interval {
     desc {
-      en: """Data collection interval."""
+      en: """The sampling interval for metrics."""
-      zh: """数据收集间隔"""
+      zh: """指标的采样间隔。"""
     }
   }
 
   flush_interval {
     desc {
-      en: """Data reporting interval."""
+      en: """The push interval for metrics."""
-      zh: """数据推送间隔"""
+      zh: """指标的推送间隔。"""
     }
   }
 
   enable {
     desc {
-      en: """Turn StatsD data pushing on or off"""
+      en: """Enable or disable StatsD metrics collection and push service."""
-      zh: """开启或关闭 StatsD 数据推送"""
+      zh: """启用或禁用 StatsD 指标采集和推送服务。"""
     }
   }
 }

apps/emqx_statsd/src/emqx_statsd_api.erl

@@ -20,6 +20,7 @@
 
 -include("emqx_statsd.hrl").
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 
 -import(hoconsc, [mk/2, ref/2]).
@@ -48,14 +49,14 @@ schema("/statsd") ->
         'operationId' => statsd,
         get =>
             #{
-                description => <<"Get statsd config">>,
+                description => ?DESC(get_statsd_config_api),
                 tags => ?API_TAG_STATSD,
                 responses =>
                     #{200 => statsd_config_schema()}
             },
         put =>
             #{
-                description => <<"Set statsd config">>,
+                description => ?DESC(update_statsd_config_api),
                 tags => ?API_TAG_STATSD,
                 'requestBody' => statsd_config_schema(),
                 responses =>