Merge pull request #7662 from DDDHuang/conf_doc_ddd_part2

fix: prometheus & statsd & topic rewrite docs

apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf

@@ -0,0 +1,23 @@
+emqx_auto_subscribe_api {
+  list_auto_subscribe_api {
+    desc {
+      en: """Get auto subscribe topic list"""
+      zh: """获取自动订阅主题列表"""
+    }
+  }
+
+  update_auto_subscribe_api {
+    desc {
+      en: """Update auto subscribe topic list"""
+      zh: """更新自动订阅主题列表"""
+    }
+  }
+
+  update_auto_subscribe_api_response409 {
+    desc {
+      en: """Auto Subscribe topics max limit"""
+      zh: """超出自定订阅主题列表长度限制"""
+    }
+  }
+
+}

apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl

@@ -29,6 +29,7 @@
 -define(EXCEED_LIMIT, 'EXCEED_LIMIT').
 -define(BAD_REQUEST, 'BAD_REQUEST').
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx/include/emqx_placeholder.hrl").
 
 api_spec() ->
@@ -41,20 +42,21 @@ schema("/mqtt/auto_subscribe") ->
     #{
         'operationId' => auto_subscribe,
         get => #{
-            description => <<"Auto subscribe list">>,
+            description => ?DESC(list_auto_subscribe_api),
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe")
                 }
             },
         put => #{
-            description => <<"Update auto subscribe topic list">>,
+            description => ?DESC(update_auto_subscribe_api),
             'requestBody' => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),
-                400 => emqx_mgmt_util:error_schema(
-                                <<"Request body required">>, [?BAD_REQUEST]),
-                409 => emqx_mgmt_util:error_schema(
-                                <<"Auto Subscribe topics max limit">>, [?EXCEED_LIMIT])}}
+                409 => emqx_dashboard_swagger:error_codes(
+                    [?EXCEED_LIMIT],
+                    ?DESC(update_auto_subscribe_api_response409))
+                }
+            }
     }.
 
 %%%==============================================================================================

apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl

@@ -33,7 +33,7 @@ roots() ->
 
 fields("auto_subscribe") ->
     [ {topics, hoconsc:mk(hoconsc:array(hoconsc:ref(?MODULE, "topic")),
-                          #{desc => "List of auto-subscribe topics."})}
+                          #{desc => ?DESC(auto_subscribe)})}
     ];
 
 fields("topic") ->

apps/emqx_modules/i18n/emqx_modules_schema_i18n.conf

@@ -0,0 +1,74 @@
+emqx_modules_schema {
+
+  rewrite {
+    desc {
+      en: """The topic rewriting function of EMQX supports rewriting topic A to topic B when the client subscribes to topics, publishes messages, and cancels subscriptions according to user-configured rules.
+Each rewrite rule consists of three parts: subject filter, regular expression, and target expression.
+Under the premise that the subject rewriting function is enabled, when EMQX receives a subject-based MQTT message such as a PUBLISH message,
+it will use the subject of the message to sequentially match the subject filter part of the rule in the configuration file. If the match is successful,
+the regular expression is used to extract the information in the subject, and then replaced with the target expression to form a new subject.
+Variables in the format of $N can be used in the target expression to match the elements extracted from the regular expression.
+The value of $N is the Nth element extracted from the regular expression. For example, $1 is the regular expression. The first element extracted by the expression.
+It should be noted that EMQX uses reverse order to read the rewrite rules in the configuration file.
+When a topic can match the topic filter of multiple topic rewrite rules at the same time, EMQX will only use the first rule it matches. Rewrite.
+If the regular expression in this rule does not match the subject of the MQTT message, the rewriting will fail, and no other rules will be attempted for rewriting.
+Therefore, users need to carefully design MQTT message topics and topic rewriting rules when using them."""
+      zh: """EMQX 的主题重写功能支持根据用户配置的规则在客户端订阅主题、发布消息、取消订阅的时候将 A 主题重写为 B 主题。
+重写规则分为 Pub 规则和 Sub 规则，Pub 规则匹配 PUSHLISH 报文携带的主题，Sub 规则匹配 SUBSCRIBE、UNSUBSCRIBE 报文携带的主题。
+每条重写规则都由主题过滤器、正则表达式、目标表达式三部分组成。
+在主题重写功能开启的前提下，EMQX 在收到诸如 PUBLISH 报文等带有主题的 MQTT 报文时，将使用报文中的主题去依次匹配配置文件中规则的主题过滤器部分，一旦成功匹配，则使用正则表达式提取主题中的信息，然后替换至目标表达式以构成新的主题。
+目标表达式中可以使用 $N 这种格式的变量匹配正则表达中提取出来的元素，$N 的值为正则表达式中提取出来的第 N 个元素，比如 $1 即为正则表达式提取的第一个元素。
+需要注意的是，EMQX 使用倒序读取配置文件中的重写规则，当一条主题可以同时匹配多条主题重写规则的主题过滤器时，EMQX 仅会使用它匹配到的第一条规则进行重写，如果该条规则中的正则表达式与 MQTT 报文主题不匹配，则重写失败，不会再尝试使用其他的规则进行重写。
+因此用户在使用时需要谨慎的设计 MQTT 报文主题以及主题重写规则。"""
+    }
+    label {
+      en: """Topic Rewrite"""
+      zh: """主题重写"""
+    }
+  }
+
+  tr_source_topic {
+    desc {
+      en: """Source topic, specified by the client."""
+      zh: """源主题，客户端业务指定的主题"""
+    }
+    label {
+      en: """Source Topic"""
+      zh: """源主题"""
+    }
+  }
+
+  tr_action {
+    desc {
+      en: """subscribe: Rewrite topic when client do subscribe.
+publish: Rewrite topic when client do publish.
+all: Both"""
+      zh: """subscribe：订阅时重写主题；
+publish：发布时重写主题；
+all：全部重写主题"""
+    }
+    label {
+      en: """Action"""
+      zh: """Action"""
+    }
+  }
+
+  tr_re {
+    desc {
+      en: """Regular expressions"""
+      zh: """正则表达式"""
+    }
+  }
+
+  tr_dest_topic {
+    desc {
+      en: """Destination topic."""
+      zh: """目标主题。"""
+    }
+    label {
+      en: """Destination Topic"""
+      zh: """目标主题"""
+    }
+  }
+
+}

apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf

@@ -0,0 +1,25 @@
+emqx_rewrite_api {
+
+  list_topic_rewrite_api {
+    desc {
+      en: """List all rewrite rules"""
+      zh: """列出全部主题重写规则"""
+    }
+  }
+
+  update_topic_rewrite_api {
+    desc {
+      en: """Update all rewrite rules"""
+      zh: """更新全部主题重写规则"""
+    }
+  }
+
+
+  update_topic_rewrite_api_response413 {
+    desc {
+      en: """Rules count exceed max limit"""
+      zh: """超出主题重写规则数量上限"""
+    }
+  }
+
+}

apps/emqx_modules/src/emqx_modules_schema.erl

@@ -16,6 +16,7 @@
 
 -module(emqx_modules_schema).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 
 -behaviour(hocon_schema).
@@ -50,17 +51,17 @@ fields("rewrite") ->
         {action,
             sc(
                 hoconsc:enum([subscribe, publish, all]),
-                #{desc => <<"Action">>, example => publish}
+                #{desc => ?DESC(tr_action), example => publish}
             )},
         {source_topic,
             sc(
                 binary(),
-                #{desc => <<"Origin Topic">>, example => "x/#"}
+                #{desc => ?DESC(tr_source_topic), example => "x/#"}
             )},
         {dest_topic,
             sc(
                 binary(),
-                #{desc => <<"Destination Topic">>, example => "z/y/$1"}
+                #{desc => ?DESC(tr_dest_topic), example => "z/y/$1"}
             )},
         {re, fun regular_expression/1}
     ];
@@ -72,14 +73,14 @@ desc("telemetry") ->
 desc("delayed") ->
     "Settings for the delayed module.";
 desc("rewrite") ->
-    "Rewrite rule.";
+    ?DESC(rewrite);
 desc("topic_metrics") ->
     "";
 desc(_) ->
     undefined.
 
 regular_expression(type) -> binary();
-regular_expression(desc) -> "Regular expressions";
+regular_expression(desc) -> ?DESC(tr_re);
 regular_expression(example) -> "^x/y/(.+)$";
 regular_expression(validator) -> fun is_re/1;
 regular_expression(_) -> undefined.

apps/emqx_modules/src/emqx_rewrite_api.erl

@@ -16,6 +16,8 @@
 -module(emqx_rewrite_api).
 
 -behaviour(minirest_api).
+
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 -include("emqx_modules.hrl").
 
@@ -38,16 +40,16 @@ schema("/mqtt/topic_rewrite") ->
         'operationId' => topic_rewrite,
         get => #{
             tags => ?API_TAG_MQTT,
-            description => <<"List rewrite topic.">>,
+            description => ?DESC(list_topic_rewrite_api),
             responses => #{
                 200 => hoconsc:mk(
                     hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")),
-                    #{desc => <<"List all rewrite rules">>}
+                    #{desc => ?DESC(list_topic_rewrite_api)}
                 )
             }
         },
         put => #{
-            description => <<"Update rewrite topic">>,
+            description => ?DESC(update_topic_rewrite_api),
             tags => ?API_TAG_MQTT,
             'requestBody' => hoconsc:mk(
                 hoconsc:array(
@@ -58,11 +60,11 @@ schema("/mqtt/topic_rewrite") ->
             responses => #{
                 200 => hoconsc:mk(
                     hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")),
-                    #{desc => <<"Update rewrite topic success.">>}
+                    #{desc => ?DESC(update_topic_rewrite_api)}
                 ),
                 413 => emqx_dashboard_swagger:error_codes(
                     [?EXCEED_LIMIT],
-                    <<"Rules count exceed max limit">>
+                    ?DESC(update_topic_rewrite_api_response413)
                 )
             }
         }

apps/emqx_prometheus/i18n/emqx_prometheus_schema_i18n.conf

@@ -0,0 +1,33 @@
+emqx_prometheus_schema {
+
+  prometheus {
+    desc {
+      en: """Settings for reporting metrics to Prometheus"""
+      zh: """Prometheus 监控数据推送"""
+    }
+    label {
+      en: """Prometheus"""
+      zh: """Prometheus"""
+    }
+  }
+
+  push_gateway_server {
+    desc {
+      en: """URL of Prometheus server"""
+      zh: """Prometheus 服务器地址"""
+    }
+  }
+
+  interval {
+    desc {
+      en: """Data reporting interval, in milliseconds."""
+      zh: """数据推送间隔，单位 毫秒"""
+    }
+  }
+  enable {
+    desc {
+      en: """Turn Prometheus data pushing on or off"""
+      zh: """开启或关闭 Prometheus 数据推送"""
+    }
+  }
+}

apps/emqx_prometheus/src/emqx_prometheus_schema.erl

@@ -15,6 +15,7 @@
 %%--------------------------------------------------------------------
 -module(emqx_prometheus_schema).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 
 -behaviour(hocon_schema).
@@ -30,25 +31,25 @@ namespace() -> "prometheus".
 roots() -> ["prometheus"].
 
 fields("prometheus") ->
-    [ {push_gateway_server, sc(string(),
+    [
+        {push_gateway_server, sc(string(),
                                #{ default => "http://127.0.0.1:9091"
                                 , required => true
-                                , desc => "URL of Prometheus pushgateway."
-                                })}
-    , {interval, sc(emqx_schema:duration_ms(),
+                                , desc => ?DESC(push_gateway_server)
+                                })},
+        {interval, sc(emqx_schema:duration_ms(),
                     #{ default => "15s"
                      , required => true
-                     , desc => "Data reporting interval in milliseconds."
-                     })}
-    , {enable, sc(boolean(),
+                     , desc => ?DESC(interval)
+                     })},
+        {enable, sc(boolean(),
                   #{ default => false
                    , required => true
-                   , desc => "Enable reporting of metrics via Prometheus Pushgateway."
+                   , desc => ?DESC(enable)
                    })}
     ].
 
-desc("prometheus") ->
-    "Settings for reporting metrics to Prometheus pushgateway.";
+desc("prometheus") -> ?DESC(prometheus);
 desc(_) ->
     undefined.
 

apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf

@@ -0,0 +1,41 @@
+emqx_statsd_schema {
+
+  statsd {
+    desc {
+      en: """Settings for reporting metrics to Statsd"""
+      zh: """Statsd 监控数据推送"""
+    }
+    label {
+      en: """Statsd"""
+      zh: """Statsd"""
+    }
+  }
+
+  server {
+    desc {
+      en: """URL of Statsd server"""
+      zh: """Statsd 服务器地址"""
+    }
+  }
+
+  sample_interval {
+    desc {
+      en: """Data collection interval in second."""
+      zh: """数据收集间隔，单位 毫秒"""
+    }
+  }
+
+  flush_interval {
+    desc {
+      en: """Data reporting interval, in second."""
+      zh: """数据推送间隔，单位 毫秒"""
+    }
+  }
+
+  enable {
+    desc {
+      en: """Turn Statsd data pushing on or off"""
+      zh: """开启或关闭 Statsd 数据推送"""
+    }
+  }
+}

apps/emqx_statsd/src/emqx_statsd_schema.erl

@@ -16,6 +16,7 @@
 
 -module(emqx_statsd_schema).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 
 -behaviour(hocon_schema).
@@ -37,34 +38,33 @@ fields("statsd") ->
     [ {enable, hoconsc:mk(boolean(),
                           #{ default => false
                            , required => true
-                           , desc => "Enable statsd"
+                           , desc => ?DESC(enable)
                            })}
     , {server, fun server/1}
     , {sample_time_interval, fun sample_interval/1}
     , {flush_time_interval, fun flush_interval/1}
     ].
 
-desc("statsd") ->
-    "Configuration related to reporting metrics to statsd.";
+desc("statsd") -> ?DESC(statsd);
 desc(_) ->
     undefined.
 
 server(type) -> emqx_schema:ip_port();
 server(required) -> true;
 server(default) -> "127.0.0.1:8125";
-server(desc) -> "URL of the statsd gateway.";
+server(desc) -> ?DESC(?FUNCTION_NAME);
 server(_) -> undefined.
 
 sample_interval(type) -> emqx_schema:duration_ms();
 sample_interval(required) -> true;
 sample_interval(default) -> "10s";
-sample_interval(desc) -> "Data collection interval in milliseconds.";
+sample_interval(desc) -> ?DESC(?FUNCTION_NAME);
 sample_interval(_) -> undefined.
 
 flush_interval(type) -> emqx_schema:duration_ms();
 flush_interval(required) -> true;
 flush_interval(default) -> "10s";
-flush_interval(desc) -> "Flush interval in milliseconds.";
+flush_interval(desc) -> ?DESC(?FUNCTION_NAME);
 flush_interval(_) -> undefined.
 
 to_ip_port(Str) ->