docs: expose zone config in schema doc

apps/emqx/src/emqx_schema.erl

@@ -217,14 +217,7 @@ roots(high) ->
                     importance => ?IMPORTANCE_MEDIUM
                 }
             )},
-        {zones,
-            sc(
-                map(name, ref("zone")),
-                #{
-                    desc => ?DESC(zones),
-                    importance => ?IMPORTANCE_HIDDEN
-                }
-            )}
+        {zones, zones_field_schema()}
     ] ++
         emqx_schema_hooks:injection_point(
             'roots.high',
@@ -1859,7 +1852,7 @@ base_listener(Bind) ->
                 #{
                     desc => ?DESC(base_listener_zone),
                     default => 'default',
-                    importance => ?IMPORTANCE_HIDDEN
+                    importance => ?IMPORTANCE_LOW
                 }
             )},
         {"limiter",
@@ -1883,6 +1876,22 @@ base_listener(Bind) ->
             )}
     ] ++ emqx_limiter_schema:short_paths_fields().
 
+%% @hidden Starting from 5.7, listenrs.{TYPE}.{NAME}.zone is no longer hidden
+%% However, the root key 'zones' is still hidden because the fields' schema
+%% just repeat other root field's schema, which makes the dumped schema doc
+%% unnecessarily bloated.
+%%
+%% zone schema is documented here since 5.7:
+%% https://docs.emqx.com/en/enterprise/latest/configuration/configuration.html
+zones_field_schema() ->
+    sc(
+        map(name, ref("zone")),
+        #{
+            desc => ?DESC(zones),
+            importance => ?IMPORTANCE_HIDDEN
+        }
+    ).
+
 desc("persistent_session_store") ->
     "Settings for message persistence.";
 desc("persistent_session_builtin") ->

rel/i18n/emqx_schema.hocon

@@ -1198,11 +1198,18 @@ fields_mqtt_quic_listener_max_ack_delay_ms.desc:
 fields_mqtt_quic_listener_max_ack_delay_ms.label:
 """Max ack delay ms"""
 
-base_listener_zone.desc:
-"""The configuration zone to which the listener belongs."""
+base_listener_zone.desc: """~
+    The configuration zone to which the listener belongs.
+    Clients connected to this listener will inherit zone-settings created under this zone name.
 
-base_listener_zone.label:
-"""Zone"""
+    A zone can override the configs under below root names:
+    - `mqtt`
+    - `force_shutdown`
+    - `force_gc`
+    - `flapping_detect`
+    - `session_persistence`"""
+
+base_listener_zone.label: "Zone"
 
 fields_mqtt_quic_listener_handshake_idle_timeout.desc:
 """How long a handshake can idle before it is discarded."""