From 81b5d7959b0192e140a945d8f508111efd8c16bb Mon Sep 17 00:00:00 2001
From: JianBo He <heeejianbo@gmail.com>
Date: Tue, 26 Apr 2022 10:01:39 +0800
Subject: [PATCH] chore(i18n): add desc for authentication field

---
 apps/emqx/i18n/emqx_schema_i18n.conf | 42 +++++++++++++++++++++++++---
 apps/emqx/src/emqx_schema.erl        | 42 ++++++----------------------
 2 files changed, 47 insertions(+), 37 deletions(-)

diff --git a/apps/emqx/i18n/emqx_schema_i18n.conf b/apps/emqx/i18n/emqx_schema_i18n.conf
index 197af9777..bd507a5bf 100644
--- a/apps/emqx/i18n/emqx_schema_i18n.conf
+++ b/apps/emqx/i18n/emqx_schema_i18n.conf
@@ -1877,7 +1877,40 @@ Timeout for proxy protocol. EMQX will close the TCP connection if proxy protocol
     }
 }
 
-authentication_0 {
+global_authentication {
+    desc {
+        en: """Default authentication configs for all MQTT listeners.
+
+For per-listener overrides see <code>authentication</code> in listener configs
+
+This option can be configured with:
+<ul>
+  <li><code>[]</code>: The default value, it allows *ALL* logins</li>
+  <li>one: For example <code>{enable:true,backend:\"built_in_database\",mechanism=\"password_based\"}</code></li>
+  <li>chain: An array of structs.</li>
+</ul>
+
+When a chain is configured, the login credentials are checked against the backends per the configured order, until an 'allow' or 'deny' decision can be made.
+
+If there is no decision after a full chain exhaustion, the login is rejected.
+"""
+        zh: """全局 MQTT 监听器的默认认证配置。 为每个监听器配置认证参考监听器器配置中的<code>authentication</code> 配置。
+
+该配置可以被配置为：
+<ul>
+  <li><code>[]</code>: 默认值，允许所以登录请求
+  <li>配置为单认证器，例如 <code>{enable:true,backend:\"built_in_database\",mechanism=\"password_based\"}</code></li>
+  <li>配置为认证器数组</li>
+</ul>
+
+当配置为认证链后，登录凭证会按照配置的顺序进行检查，直到做出<code>allow</code> 或 <code>deny</code>的结果。
+
+如果在所有的认证器都执行完后，还是没有结果，登录将被拒绝。
+"""
+    }
+}
+
+listener_authentication {
     desc {
         en: """
 Per-listener authentication override.
@@ -1886,9 +1919,10 @@ When authenticating a login (username, client ID, etc.) the authenticators are c
 
 """
         zh: """
-每侦听器身份验证覆盖。
-身份验证可以是单个身份验证程序实例，也可以是一个数组形式的身份验证程序链。
-验证登录名（用户名、客户端ID等）时，将按配置的顺序检查验证器</br>
+监听器认证重载。
+
+认证配置可以是单个认证器实例，也可以是一个认证器数组组成的认证链。
+执行登录验证时（用户名、客户端 ID 等），将按配置的顺序执行</br>
 """
     }
     label: {
diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index 8282d35bb..4a23bfeda 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -125,28 +125,7 @@ roots(high) ->
                 ref("mqtt"),
                 #{desc => ?DESC(mqtt)}
             )},
-        {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME,
-            authentication(
-                "Default authentication configs for all MQTT listeners.\n"
-                "</br>\n"
-                "For per-listener overrides see <code>authentication</code>\n"
-                "in listener configs\n"
-                "</br>\n"
-                "</br>\n"
-                "EMQX can be configured with:\n"
-                "</br>\n"
-                "<ul>\n"
-                "<li><code>[]</code>: The default value, it allows *ALL* logins</li>\n"
-                "<li>one: For example <code>{enable:true,backend:\"built_in_database\",mechanism=\"password_based\"}\n"
-                "</code></li>\n"
-                "<li>chain: An array of structs.</li>\n"
-                "</ul>\n"
-                "</br>\n"
-                "When a chain is configured, the login credentials are checked against the backends\n"
-                "per the configured order, until an 'allow' or 'deny' decision can be made.\n"
-                "</br>\n"
-                "If there is no decision after a full chain exhaustion, the login is rejected.\n"
-            )},
+        {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME, authentication(global)},
         %% NOTE: authorization schema here is only to keep emqx app prue
         %% the full schema for EMQX node is injected in emqx_conf_schema.
         {?EMQX_AUTHORIZATION_CONFIG_ROOT_NAME,
@@ -1521,8 +1500,7 @@ mqtt_listener() ->
                         default => "3s"
                     }
                 )},
-            {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME,
-                authentication("Per-listener authentication override")}
+            {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME, authentication(listener)}
         ].
 
 base_listener() ->
@@ -2170,7 +2148,12 @@ str(B) when is_binary(B) ->
 str(S) when is_list(S) ->
     S.
 
-authentication(Desc) ->
+authentication(Type) ->
+    Desc =
+        case Type of
+            global -> ?DESC(global_authentication);
+            listener -> ?DESC(listener_authentication)
+        end,
     %% authentication schema is lazy to make it more 'plugable'
     %% the type checks are done in emqx_auth application when it boots.
     %% and in emqx_authentication_config module for runtime changes.
@@ -2188,14 +2171,7 @@ authentication(Desc) ->
                 undefined -> Default;
                 Module -> hoconsc:lazy(Module:root_type())
             end,
-        desc_id => "authentication_0",
-        desc => iolist_to_binary([
-            Desc,
-            "\nAuthentication can be one single authenticator instance or a chain of "
-            "authenticators as an array.\n"
-            "When authenticating a login (username, client ID, etc.) "
-            "the authenticators are checked in the configured order.</br>\n"
-        ])
+        desc => Desc
     }.
 
 -spec qos() -> typerefl:type().