Merge pull request #12939 from zmstone/0426-unhide-zone-config-for-listener

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

mix.exs

@@ -101,7 +101,8 @@ defmodule EMQXUmbrella.MixProject do
       {:bcrypt, github: "emqx/erlang-bcrypt", tag: "0.6.2", override: true},
       {:uuid, github: "okeuday/uuid", tag: "v2.0.6", override: true},
       {:quickrand, github: "okeuday/quickrand", tag: "v2.0.6", override: true},
-      {:ra, "2.7.3", override: true}
+      {:ra, "2.7.3", override: true},
+      {:mimerl, "1.2.0", override: true}
     ] ++
       emqx_apps(profile_info, version) ++
       enterprise_deps(profile_info) ++ jq_dep() ++ quicer_dep()

rebar.config

@@ -111,7 +111,8 @@
     {ssl_verify_fun, "1.1.7"},
     {rfc3339, {git, "https://github.com/emqx/rfc3339.git", {tag, "0.2.3"}}},
     {bcrypt, {git, "https://github.com/emqx/erlang-bcrypt.git", {tag, "0.6.2"}}},
-    {ra, "2.7.3"}
+    {ra, "2.7.3"},
+    {mimerl, "1.2.0"}
 ]}.
 
 {xref_ignores,

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.label:
-"""Zone"""
+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.
+
+    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."""