From d1a15f1a431e72bcd72bfbd0becfd4dd0a6e2445 Mon Sep 17 00:00:00 2001 From: zhouzb Date: Fri, 30 Sep 2022 15:05:01 +0800 Subject: [PATCH 1/3] chore: improve api descs for banned --- .../i18n/emqx_mgmt_api_banned_i18n.conf | 83 ++++++++----------- 1 file changed, 34 insertions(+), 49 deletions(-) diff --git a/apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf b/apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf index 686293d0b..6bc736f9e 100644 --- a/apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf +++ b/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.""" - zh: """列出黑名单""" - } - label { - en: """List Banned""" - zh: """列出黑名单""" + en: """List all currently banned client IDs, usernames and IP addresses.""" + zh: """列出目前所有被封禁的客户端 ID、用户名和 IP 地址。""" } } create_banned_api { desc { - en: """Create banned.""" - zh: """创建黑名单""" + en: """Add a client ID, username or IP address to the blacklist.""" + zh: """添加一个客户端 ID、用户名或者 IP 地址到黑名单。""" } } create_banned_api_response400 { desc { - en: """Banned already existed, or bad args.""" - zh: """黑名单已存在，或参数格式有错误""" + en: """Bad request, possibly due to wrong parameters or the existence of a banned object.""" + zh: """错误的请求，可能是参数错误或封禁对象已存在等原因。""" } } delete_banned_api { desc { - en: """Delete banned""" - zh: """删除黑名单""" + en: """Remove a client ID, username or IP address from the blacklist.""" + zh: """将一个客户端 ID、用户名或者 IP 地址从黑名单中删除。""" } } delete_banned_api_response404 { desc { - en: """Banned not found. May be the banned time has been exceeded""" - zh: """黑名单未找到，可能为已经超期失效""" - } - } - - create_banned { - desc { - en: """List banned.""" - zh: """列出黑名单""" - } - label { - en: """List Banned""" - zh: """列出黑名单""" + en: """The banned object was not found in the blacklist.""" + zh: """未在黑名单中找到该封禁对象。""" } } as { desc { - en: """Banned type clientid, username, peerhost""" - zh: """黑名单类型，可选 clientid、username、peerhost""" + en: """Ban method, which can be client ID, username or IP address.""" + zh: """封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。""" } label { - en: """Banned Type""" - zh: """黑名单类型""" + en: """Ban Method""" + zh: """封禁方式""" } } who { desc { - en: """Client info as banned type""" - zh: """设备信息""" + en: """Ban object, specific client ID, username or IP address.""" + zh: """封禁对象，具体的客户端 ID、用户名或者 IP 地址。""" } label { - en: """Banned Info""" - zh: """黑名单信息""" + en: """Ban Object""" + zh: """封禁对象""" } } by { desc { - en: """Commander""" - zh: """黑名单创建者""" + en: """Initiator of the ban.""" + zh: """封禁的发起者。""" } label { - en: """Commander""" - zh: """黑名单创建者""" + en: """Ban Initiator""" + zh: """封禁发起者""" } } reason { desc { - en: """Banned reason""" - zh: """黑名单创建原因""" + en: """Banned reason, record the reason why the current object was banned.""" + zh: """封禁原因，记录当前对象被封禁的原因。""" } label { - en: """Reason""" - zh: """原因""" + en: """Banned Reason""" + zh: """封禁原因""" } } at { desc { - en: """Create banned time, rfc3339, now if not specified""" - zh: """黑名单创建时间，默认为当前""" + en: """The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.""" + zh: """封禁的起始时间，格式为 rfc3339，默认为发起操作的时间。""" } label { - en: """Create banned time""" - zh: """黑名单创建时间""" + en: """Ban Time""" + zh: """封禁时间""" } } until { desc { - en: """Cancel banned time, rfc3339, now + 5 minute if not specified""" - zh: """黑名单结束时间，默认为创建时间 + 5 分钟""" + en: """The end time of the ban, the formula is rfc3339, the default is the time when the operation was initiated + 5 minutes.""" + zh: """封禁的结束时间，式为 rfc3339，默认为发起操作的时间 + 5 分钟。""" } label { - en: """Cancel banned time""" - zh: """黑名单结束时间""" + en: """Ban End Time""" + zh: """封禁结束时间""" } } } From f08982be93cf3b46d1ac014058409b907412a677 Mon Sep 17 00:00:00 2001 From: zhouzb Date: Fri, 30 Sep 2022 15:34:49 +0800 Subject: [PATCH 2/3] chore: improve api desc for alarms --- .../i18n/emqx_mgmt_api_alarms_i18n.conf | 48 ++++++++++--------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf b/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf index c6f518c86..f50e40b62 100644 --- a/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf +++ b/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""" - zh: """列出告警，获取告警列表""" + en: """List currently activated alarms or historical alarms, determined by query parameters.""" + zh: """列出当前激活的告警或历史告警，由查询参数决定。""" } } delete_alarms_api { desc { - en: """Remove all deactivated alarms""" - zh: """删除所有历史告警（非活跃告警）""" + en: """Remove all historical alarms.""" + zh: """删除所有历史告警。""" } } delete_alarms_api_response204 { desc { - en: """Remove all deactivated alarms ok""" - zh: """删除所有历史告警（非活跃告警）成功""" + en: """Historical alarms have been cleared successfully.""" + zh: """历史告警已成功清除。""" } } get_alarms_qs_activated { desc { - en: """Activate alarms, or deactivate alarms. Default is false""" - zh: """活跃中的告警，或历史告警（非活跃告警），默认为 false""" + en: """It is used to specify the alarm type of the query. +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""" - zh: """告警节点名称""" + en: """The name of the node that triggered this alarm.""" + zh: """触发此告警的节点名称。""" } } name { desc { - en: """Alarm name""" - zh: """告警名称""" + en: """Alarm name, used to distinguish different alarms.""" + zh: """告警名称，用于区分不同的告警。""" } } message { desc { - en: """Alarm readable information""" - zh: """告警信息""" + en: """Alarm message, which describes the alarm content in a human-readable format.""" + zh: """告警消息，以人类可读的方式描述告警内容。""" } } details { desc { - en: """Alarm details information""" - zh: """告警详细信息""" + en: """Alarm details, provides more alarm information, mainly for program processing.""" + zh: """告警详情，提供了更多的告警信息，主要提供给程序处理。""" } } duration { desc { - en: """Alarms duration time; UNIX time stamp, millisecond""" - zh: """告警持续时间，单位：毫秒""" + en: """Indicates how long the alarm has lasted, in milliseconds.""" + zh: """表明告警已经持续了多久，单位：毫秒。""" } } activate_at { desc { - en: """Alarms activate time, RFC 3339""" - zh: """告警开始时间，使用 rfc3339 标准时间格式""" + en: """Alarm start time, using rfc3339 standard time format.""" + zh: """告警开始时间，使用 rfc3339 标准时间格式。""" } } deactivate_at { desc { - en: """Alarms deactivate time, RFC 3339""" - zh: """告警结束时间，使用 rfc3339 标准时间格式""" + en: """Alarm end time, in the rfc3339 standard time format.""" + zh: """告警结束时间，使用 rfc3339 标准时间格式。""" } } From 0975bf21a99f444263d9070c2dd797885bad5c81 Mon Sep 17 00:00:00 2001 From: zhouzb Date: Fri, 30 Sep 2022 17:55:12 +0800 Subject: [PATCH 3/3] docs: improve api desc for statsd --- .../i18n/emqx_mgmt_api_alarms_i18n.conf | 2 +- .../i18n/emqx_statsd_schema_i18n.conf | 34 +++++++++++++------ apps/emqx_statsd/src/emqx_statsd_api.erl | 5 +-- 3 files changed, 28 insertions(+), 13 deletions(-) diff --git a/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf b/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf index f50e40b62..8932df048 100644 --- a/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf +++ b/apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf @@ -76,7 +76,7 @@ The default is false.""" deactivate_at { desc { - en: """Alarm end time, in the rfc3339 standard time format.""" + en: """Alarm end time, using rfc3339 standard time format.""" zh: """告警结束时间，使用 rfc3339 标准时间格式。""" } } diff --git a/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf b/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf index 4ccad1682..9c6eb5afb 100644 --- a/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf +++ b/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""" - zh: """StatsD 监控数据推送""" + en: """StatsD metrics collection and push configuration.""" + zh: """StatsD 指标采集与推送配置。""" } label { en: """StatsD""" @@ -13,29 +27,29 @@ emqx_statsd_schema { server { desc { - en: """URL of StatsD server""" - zh: """StatsD 服务器地址""" + en: """StatsD server address.""" + zh: """StatsD 服务器地址。""" } } sample_interval { desc { - en: """Data collection interval.""" - zh: """数据收集间隔""" + en: """The sampling interval for metrics.""" + zh: """指标的采样间隔。""" } } flush_interval { desc { - en: """Data reporting interval.""" - zh: """数据推送间隔""" + en: """The push interval for metrics.""" + zh: """指标的推送间隔。""" } } enable { desc { - en: """Turn StatsD data pushing on or off""" - zh: """开启或关闭 StatsD 数据推送""" + en: """Enable or disable StatsD metrics collection and push service.""" + zh: """启用或禁用 StatsD 指标采集和推送服务。""" } } } diff --git a/apps/emqx_statsd/src/emqx_statsd_api.erl b/apps/emqx_statsd/src/emqx_statsd_api.erl index ee6007d7d..2f2e42303 100644 --- a/apps/emqx_statsd/src/emqx_statsd_api.erl +++ b/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 =>