Merge pull request #7655 from DDDHuang/conf_doc_ddd

Conf docs

apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_i18n.conf

@@ -0,0 +1,85 @@
+emqx_auto_subscribe_schema {
+  auto_subscribe {
+    desc {
+      en: """After the device logs in successfully, the subscription is automatically completed for the device through the pre-defined subscription representation. Supports the use of placeholders."""
+      zh: """设备登陆成功之后，通过预设的订阅表示符，为设备自动完成订阅。支持使用占位符。"""
+    }
+    lable {
+      en: """Auto Subscribe"""
+      zh: """自动订阅"""
+    }
+  }
+
+  topic {
+    desc {
+      en: """Topic name, placeholders are supported. For example: client/${clientid}/username/${username}/host/${host}/port/${port}
+Required field, and cannot be empty string"""
+      zh: """订阅标识符，支持使用占位符，例如 client/${clientid}/username/${username}/host/${host}/port/${port}
+必填，且不可为空字符串"""
+    }
+    label {
+      en: """Topic"""
+      zh: """订阅标识符"""
+    }
+  }
+
+  qos {
+    desc {
+      en: """Default value 0. Quality of service.
+At most once (0)
+At least once (1)
+Exactly once (2)"""
+      zh: """缺省值为 0，服务质量，
+QoS 0：消息最多传递一次，如果当时客户端不可用，则会丢失该消息。
+QoS 1：消息传递至少 1 次。
+QoS 2：消息仅传送一次。"""
+    }
+    label {
+      en: """Quality of Service"""
+      zh: """服务质量"""
+    }
+  }
+
+  rh {
+    desc {
+      en: """Default value 0. This option is used to specify whether the server forwards the retained message to the client when establishing a subscription.
+Retain Handling is equal to 0, as long as the client successfully subscribes, the server will send the retained message.
+Retain Handling is equal to 1, if the client successfully subscribes and this subscription does not exist previously, the server sends the retained message. After all, sometimes the client re-initiate the subscription just to change the QoS, but it does not mean that it wants to receive the reserved messages again.
+Retain Handling is equal to 2, even if the client successfully subscribes, the server does not send the retained message."""
+      zh: """指定订阅建立时服务端是否向客户端发送保留消息，
+可选值 0：只要客户端订阅成功，服务端就发送保留消息。
+可选值 1：客户端订阅成功且该订阅此前不存在，服务端才发送保留消息。毕竟有些时候客户端重新发起订阅可能只是为了改变一下 QoS，并不意味着它想再次接收保留消息。
+可选值 2：即便客户订阅成功，服务端也不会发送保留消息。"""
+    }
+    label {
+      en: """Retain Handling"""
+      zh: """Retain Handling"""
+    }
+  }
+
+  rap {
+    desc {
+      en: """Default value 0. This option is used to specify whether the server retains the RETAIN mark when forwarding messages to the client, and this option does not affect the RETAIN mark in the retained message. Therefore, when the option Retain As Publish is set to 0, the client will directly distinguish whether this is a normal forwarded message or a retained message according to the RETAIN mark in the message, instead of judging whether this message is the first received after subscribing(the forwarded message may be sent before the retained message, which depends on the specific implementation of different brokers)."""
+      zh: """缺省值为 0，这一选项用来指定服务端向客户端转发消息时是否要保留其中的 RETAIN 标识，注意这一选项不会影响保留消息中的 RETAIN 标识。因此当 Retain As Publish 选项被设置为 0 时，客户端直接依靠消息中的 RETAIN 标识来区分这是一个正常的转发消息还是一个保留消息，而不是去判断消息是否是自己订阅后收到的第一个消息（转发消息甚至可能会先于保留消息被发送，视不同 Broker 的具体实现而定）。"""
+    }
+    label {
+      en: """Retain As Publish"""
+      zh: """Retain As Publish"""
+    }
+  }
+
+  nl {
+    desc {
+      en: """Default value 0.
+MQTT v3.1.1： if you subscribe to the topic published by yourself, you will receive all messages that you published.
+MQTT v5: if you set this option as 1 when subscribing, the server will not forward the message you published to you."""
+      zh: """缺省值为0，
+MQTT v3.1.1：如果设备订阅了自己发布消息的主题，那么将收到自己发布的所有消息。
+MQTT v5：如果设备在订阅时将此选项设置为 1，那么服务端将不会向设备转发自己发布的消息"""
+    }
+    label {
+      en: """No Local"""
+      zh: """No Local"""
+    }
+  }
+}

apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl

@@ -17,6 +17,7 @@
 
 -behaviour(hocon_schema).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 -include_lib("emqx/include/emqx_placeholder.hrl").
 
@@ -38,28 +39,24 @@ fields("auto_subscribe") ->
 fields("topic") ->
     [ {topic, sc(binary(), #{
         example => topic_example(),
-        desc => "Topic name, placeholders is supported. For example: "
-                ++ binary_to_list(topic_example())})}
+        desc => ?DESC("topic")})}
     , {qos, sc(emqx_schema:qos(), #{
         default => 0,
-        desc => "Quality of service. MQTT definition."})}
+        desc => ?DESC("qos")})}
     , {rh, sc(range(0,2), #{
         default => 0,
-        desc => "Retain handling. MQTT 5.0 definition."})}
+        desc => ?DESC("rh")})}
     , {rap, sc(range(0, 1), #{
         default => 0,
-        desc => "Retain as Published. MQTT 5.0 definition."})}
+        desc => ?DESC("rap")})}
     , {nl, sc(range(0, 1), #{
         default => 0,
-        desc => "Not local. MQTT 5.0 definition."})}
+        desc => ?DESC(nl)})}
     ].
 
-desc("auto_subscribe") ->
-    "Configuration for `auto_subscribe` feature.";
-desc("topic") ->
-    "";
-desc(_) ->
-    undefined.
+desc("auto_subscribe") -> ?DESC("auto_subscribe");
+desc("topic") -> ?DESC("topic");
+desc(_) -> undefined.
 
 topic_example() ->
     <<"/clientid/", ?PH_S_CLIENTID,

apps/emqx_dashboard/src/emqx_dashboard_swagger.erl

@@ -149,14 +149,14 @@ schema_with_examples(Type, Examples) ->
 error_codes(Codes) ->
     error_codes(Codes, <<"Error code to troubleshoot problems.">>).
 
--spec error_codes(nonempty_list(atom()), binary()) -> hocon_schema:fields().
-error_codes(Codes = [_ | _], MsgExample) ->
+-spec error_codes(nonempty_list(atom()), binary() | {desc, module(), term()}) ->
+    hocon_schema:fields().
+error_codes(Codes = [_ | _], MsgDesc) ->
     [
         {code, hoconsc:mk(hoconsc:enum(Codes))},
         {message,
             hoconsc:mk(string(), #{
-                desc => <<"Details description of the error.">>,
-                example => MsgExample
+                desc => MsgDesc
             })}
     ].
 
@@ -443,6 +443,9 @@ responses(Responses, Module, Options) ->
     {Spec, Refs, _, _} = maps:fold(fun response/3, {#{}, [], Module, Options}, Responses),
     {Spec, Refs}.
 
+response(Status, ?DESC(_Mod, _Id) = Schema, {Acc, RefsAcc, Module, Options}) ->
+    Desc = trans_description(#{}, #{desc => Schema}),
+    {Acc#{integer_to_binary(Status) => Desc}, RefsAcc, Module, Options};
 response(Status, Bin, {Acc, RefsAcc, Module, Options}) when is_binary(Bin) ->
     {Acc#{integer_to_binary(Status) => #{description => Bin}}, RefsAcc, Module, Options};
 %% Support swagger raw object(file download).

apps/emqx_dashboard/test/emqx_swagger_response_SUITE.erl

@@ -67,16 +67,15 @@ t_error(_Config) ->
         <<"properties">> =>
         [
             {<<"code">>, #{enum => ['Bad1', 'Bad2'], type => string}},
-            {<<"message">>, #{description => <<"Details description of the error.">>,
-                example => <<"Bad request desc">>, type => string}}]
+            {<<"message">>, #{description => <<"Bad request desc">>, type => string}}]
     }}}},
     Error404 = #{<<"content">> =>
     #{<<"application/json">> => #{<<"schema">> => #{<<"type">> => object,
         <<"properties">> =>
         [
             {<<"code">>, #{enum => ['Not-Found'], type => string}},
-            {<<"message">>, #{description => <<"Details description of the error.">>,
-                example => <<"Error code to troubleshoot problems.">>, type => string}}]
+            {<<"message">>, #{
+                description => <<"Error code to troubleshoot problems.">>, type => string}}]
     }}}},
     {OperationId, Spec, Refs} = emqx_dashboard_swagger:parse_spec_ref(?MODULE, Path, #{}),
     ?assertEqual(test, OperationId),

apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf

@@ -0,0 +1,80 @@
+emqx_mgmt_api_alarms {
+
+    list_alarms_api {
+        desc {
+            en: """List alarms"""
+            zh: """列出告警，获取告警列表"""
+        }
+    }
+
+    delete_alarms_api {
+        desc {
+            en: """Remove all deactivated alarms"""
+            zh: """删除所有历史告警（非活跃告警）"""
+        }
+    }
+
+    delete_alarms_api_response204 {
+        desc {
+            en: """Remove all deactivated alarms ok"""
+            zh: """删除所有历史告警（非活跃告警）成功"""
+        }
+    }
+
+    get_alarms_qs_activated {
+        desc {
+            en: """Activate alarms, or deactivate alarms. Default is false"""
+            zh: """活跃中的告警，或历史告警（非活跃告警），默认为 false"""
+        }
+    }
+
+    node {
+        desc {
+            en: """Alarm in node"""
+            zh: """告警节点名称"""
+        }
+    }
+
+    name {
+        desc {
+            en: """Alarm name"""
+            zh: """告警名称"""
+        }
+    }
+
+    message {
+        desc {
+            en: """Alarm readable information"""
+            zh: """告警信息"""
+        }
+    }
+
+    details {
+        desc {
+            en: """Alarm details information"""
+            zh: """告警详细信息"""
+        }
+    }
+
+    duration {
+        desc {
+            en: """Alarms duration time; UNIX time stamp, millisecond"""
+            zh: """告警持续时间，单位：毫秒"""
+        }
+    }
+
+    activate_at {
+        desc {
+            en: """Alarms activate time, RFC 3339"""
+            zh: """告警开始时间，使用 rfc3339 标准时间格式"""
+        }
+    }
+
+    deactivate_at {
+        desc {
+            en: """Alarms deactivate time, RFC 3339"""
+            zh: """告警结束时间，使用 rfc3339 标准时间格式"""
+        }
+    }
+
+}

apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf

@@ -0,0 +1,113 @@
+emqx_mgmt_api_banned {
+
+    list_banned_api {
+        desc {
+            en: """List banned."""
+            zh: """列出黑名单"""
+        }
+        label {
+            en: """List Banned"""
+            zh: """列出黑名单"""
+        }
+    }
+
+    create_banned_api {
+        desc {
+            en: """Create banned."""
+            zh: """创建黑名单"""
+        }
+    }
+
+    create_banned_api_response400 {
+        desc {
+            en: """Banned already existed, or bad args."""
+            zh: """黑名单已存在，或参数格式有错误"""
+        }
+    }
+
+    delete_banned_api {
+        desc {
+            en: """Delete banned"""
+            zh: """删除黑名单"""
+        }
+    }
+
+    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: """列出黑名单"""
+        }
+    }
+
+    as {
+        desc {
+            en: """Banned type clientid, username, peerhost"""
+            zh: """黑名单类型，可选 clientid、username、peerhost"""
+        }
+        label {
+            en: """Banned Type"""
+            zh: """黑名单类型"""
+        }
+    }
+    who {
+        desc {
+            en: """Client info as banned type"""
+            zh: """设备信息"""
+        }
+        label {
+            en: """Banned Info"""
+            zh: """黑名单信息"""
+        }
+    }
+    by {
+        desc {
+            en: """Commander"""
+            zh: """黑名单创建者"""
+        }
+        label {
+            en: """Commander"""
+            zh: """黑名单创建者"""
+        }
+    }
+    reason {
+        desc {
+            en: """Banned reason"""
+            zh: """黑名单创建原因"""
+        }
+        label {
+            en: """Reason"""
+            zh: """原因"""
+        }
+    }
+    at {
+        desc {
+            en: """Create banned time, rfc3339, now if not specified"""
+            zh: """黑名单创建时间，默认为当前"""
+        }
+        label {
+            en: """Create banned time"""
+            zh: """黑名单创建时间"""
+        }
+    }
+    until {
+        desc {
+            en: """Cancel banned time, rfc3339, now + 5 minute if not specified"""
+            zh: """黑名单结束时间，默认为创建时间 + 5 分钟"""
+        }
+        label {
+            en: """Cancel banned time"""
+            zh: """黑名单结束时间"""
+        }
+    }
+}

apps/emqx_management/src/emqx_mgmt_api_alarms.erl

@@ -18,6 +18,7 @@
 
 -behaviour(minirest_api).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx/include/emqx.hrl").
 -include_lib("typerefl/include/types.hrl").
 
@@ -38,12 +39,12 @@ schema("/alarms") ->
     #{
         'operationId' => alarms,
         get => #{
-            description => <<"EMQX alarms">>,
+            description => ?DESC(list_alarms_api),
             parameters => [
                 hoconsc:ref(emqx_dashboard_swagger, page),
                 hoconsc:ref(emqx_dashboard_swagger, limit),
                 {activated, hoconsc:mk(boolean(), #{in => query,
-                    desc => <<"All alarms, if not specified">>,
+                    desc => ?DESC(get_alarms_qs_activated),
                     required => false})}
             ],
             responses => #{
@@ -54,9 +55,9 @@ schema("/alarms") ->
             }
         },
         delete  => #{
-            description => <<"Remove all deactivated alarms">>,
+            description => ?DESC(delete_alarms_api),
             responses => #{
-                204 => <<"Remove all deactivated alarms ok">>
+                204 => ?DESC(delete_alarms_api_response204)
             }
         }
     }.
@@ -64,20 +65,17 @@ schema("/alarms") ->
 fields(alarm) ->
     [
         {node, hoconsc:mk(binary(),
-                          #{desc => <<"Alarm in node">>, example => atom_to_list(node())})},
+                          #{desc => ?DESC(node), example => atom_to_list(node())})},
         {name, hoconsc:mk(binary(),
-                          #{desc => <<"Alarm name">>, example => <<"high_system_memory_usage">>})},
-        {message, hoconsc:mk(binary(), #{desc => <<"Alarm readable information">>,
+                          #{desc => ?DESC(node), example => <<"high_system_memory_usage">>})},
+        {message, hoconsc:mk(binary(), #{desc => ?DESC(message),
             example => <<"System memory usage is higher than 70%">>})},
-        {details, hoconsc:mk(map(), #{desc => <<"Alarm details information">>,
+        {details, hoconsc:mk(map(), #{desc => ?DESC(details),
             example => #{<<"high_watermark">> => 70}})},
-        {duration, hoconsc:mk(integer(),
-                              #{desc => <<"Alarms duration time; UNIX time stamp, millisecond">>,
-            example => 297056})},
-        {activate_at, hoconsc:mk(binary(), #{desc => <<"Alarms activate time, RFC 3339">>,
+        {duration, hoconsc:mk(integer(), #{desc => ?DESC(duration), example => 297056})},
+        {activate_at, hoconsc:mk(binary(), #{desc => ?DESC(activate_at),
             example => <<"2021-10-25T11:52:52.548+08:00">>})},
-        {deactivate_at, hoconsc:mk(binary(),
-                                   #{desc => <<"Nullable, alarms deactivate time, RFC 3339">>,
+        {deactivate_at, hoconsc:mk(binary(), #{desc => ?DESC(deactivate_at),
             example => <<"2021-10-31T10:52:52.548+08:00">>})}
     ];
 

apps/emqx_management/src/emqx_mgmt_api_banned.erl

@@ -16,6 +16,7 @@
 
 -module(emqx_mgmt_api_banned).
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("emqx/include/emqx.hrl").
 -include_lib("typerefl/include/types.hrl").
 
@@ -50,7 +51,7 @@ schema("/banned") ->
     #{
         'operationId' =>  banned,
         get => #{
-            description => <<"List banned">>,
+            description => ?DESC(list_banned_api),
             parameters => [
                 hoconsc:ref(emqx_dashboard_swagger, page),
                 hoconsc:ref(emqx_dashboard_swagger, limit)
@@ -63,13 +64,13 @@ schema("/banned") ->
             }
         },
         post => #{
-            description => <<"Create banned">>,
+            description => ?DESC(create_banned_api),
             'requestBody' => hoconsc:mk(hoconsc:ref(ban)),
             responses => #{
                 200 => [{data, hoconsc:mk(hoconsc:array(hoconsc:ref(ban)), #{})}],
                 400 => emqx_dashboard_swagger:error_codes(
                            ['ALREADY_EXISTS', 'BAD_REQUEST'],
-                            <<"Banned already existed, or bad args">>)
+                           ?DESC(create_banned_api_response400))
             }
         }
     };
@@ -77,14 +78,14 @@ schema("/banned/:as/:who") ->
     #{
         'operationId' => delete_banned,
         delete => #{
-            description => <<"Delete banned">>,
+            description => ?DESC(delete_banned_api),
             parameters => [
                 {as, hoconsc:mk(hoconsc:enum(?BANNED_TYPES), #{
-                    desc => <<"Banned type">>,
+                    desc => ?DESC(as),
                     in => path,
                     example => username})},
                 {who, hoconsc:mk(binary(), #{
-                    desc => <<"Client info as banned type">>,
+                    desc => ?DESC(who),
                     in => path,
                     example => <<"Badass">>})}
                 ],
@@ -92,7 +93,7 @@ schema("/banned/:as/:who") ->
                 204 => <<"Delete banned success">>,
                 404 => emqx_dashboard_swagger:error_codes(
                            ['NOT_FOUND'],
-                            <<"Banned not found. May be the banned time has been exceeded">>)
+                           ?DESC(delete_banned_api_response404))
             }
         }
     }.
@@ -100,27 +101,27 @@ schema("/banned/:as/:who") ->
 fields(ban) ->
     [
         {as, hoconsc:mk(hoconsc:enum(?BANNED_TYPES), #{
-            desc => <<"Banned type clientid, username, peerhost">>,
+            desc => ?DESC(as),
             required => true,
             example => username})},
         {who, hoconsc:mk(binary(), #{
-            desc => <<"Client info as banned type">>,
+            desc => ?DESC(who),
             required => true,
             example => <<"Banned name"/utf8>>})},
         {by, hoconsc:mk(binary(), #{
-            desc => <<"Commander">>,
+            desc => ?DESC(by),
             required => false,
             example => <<"mgmt_api">>})},
         {reason, hoconsc:mk(binary(), #{
-            desc => <<"Banned reason">>,
+            desc => ?DESC(reason),
             required => false,
             example => <<"Too many requests">>})},
         {at, hoconsc:mk(emqx_datetime:epoch_second(), #{
-            desc => <<"Create banned time, rfc3339, now if not specified">>,
+            desc => ?DESC(at),
             required => false,
             example => <<"2021-10-25T21:48:47+08:00">>})},
         {until, hoconsc:mk(emqx_datetime:epoch_second(), #{
-            desc => <<"Cancel banned time, rfc3339, now + 5 minute if not specified">>,
+            desc => ?DESC(until),
             required => false,
             example => <<"2021-10-25T21:53:47+08:00">>})
         }