From 0975bf21a99f444263d9070c2dd797885bad5c81 Mon Sep 17 00:00:00 2001
From: zhouzb <zhouzb@emqx.io>
Date: Fri, 30 Sep 2022 17:55:12 +0800
Subject: [PATCH] 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 =>