Merge pull request #7655 from DDDHuang/conf_doc_ddd

Conf docs

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">>})
         }