Merge pull request #10724 from kjellwinblad/kjell/docs/missing_http_a…

…pi_endpoint_descriptions/EMQX-9767

docs: make sure there is a summary for all API endpoints

apps/emqx_dashboard/src/emqx_dashboard.app.src

@@ -2,7 +2,7 @@
 {application, emqx_dashboard, [
     {description, "EMQX Web Dashboard"},
     % strict semver, bump manually!
-    {vsn, "5.0.20"},
+    {vsn, "5.0.21"},
     {modules, []},
     {registered, [emqx_dashboard_sup]},
     {applications, [kernel, stdlib, mnesia, minirest, emqx, emqx_ctl]},

apps/emqx_dashboard/src/emqx_dashboard_error_code_api.erl

@@ -20,6 +20,7 @@
 -include_lib("emqx/include/http_api.hrl").
 -include("emqx_dashboard.hrl").
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -export([
     api_spec/0,
@@ -50,7 +51,7 @@ schema("/error_codes") ->
         'operationId' => error_codes,
         get => #{
             security => [],
-            description => <<"API Error Codes">>,
+            description => ?DESC(error_codes),
             tags => [<<"Error Codes">>],
             responses => #{
                 200 => hoconsc:array(hoconsc:ref(?MODULE, error_code))
@@ -62,7 +63,7 @@ schema("/error_codes/:code") ->
         'operationId' => error_code,
         get => #{
             security => [],
-            description => <<"API Error Codes">>,
+            description => ?DESC(error_codes_u),
             tags => [<<"Error Codes">>],
             parameters => [
                 {code,

apps/emqx_dashboard/src/emqx_dashboard_monitor_api.erl

@@ -6,6 +6,7 @@
 
 -include("emqx_dashboard.hrl").
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hocon_types.hrl").
 
 -behaviour(minirest_api).
 
@@ -38,7 +39,7 @@ schema("/monitor") ->
         'operationId' => monitor,
         get => #{
             tags => [<<"Metrics">>],
-            desc => <<"List monitor data.">>,
+            description => ?DESC(list_monitor),
             parameters => [parameter_latest()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(sampler)), #{}),
@@ -51,7 +52,7 @@ schema("/monitor/nodes/:node") ->
         'operationId' => monitor,
         get => #{
             tags => [<<"Metrics">>],
-            desc => <<"List the monitor data on the node.">>,
+            description => ?DESC(list_monitor_node),
             parameters => [parameter_node(), parameter_latest()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(sampler)), #{}),
@@ -64,7 +65,7 @@ schema("/monitor_current") ->
         'operationId' => monitor_current,
         get => #{
             tags => [<<"Metrics">>],
-            desc => <<"Current status. Gauge and rate.">>,
+            description => ?DESC(current_status),
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{})
             }
@@ -75,7 +76,7 @@ schema("/monitor_current/nodes/:node") ->
         'operationId' => monitor_current,
         get => #{
             tags => [<<"Metrics">>],
-            desc => <<"Node current status. Gauge and rate.">>,
+            description => ?DESC(current_status_node),
             parameters => [parameter_node()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{}),

apps/emqx_management/src/emqx_management.app.src

@@ -2,7 +2,7 @@
 {application, emqx_management, [
     {description, "EMQX Management API and CLI"},
     % strict semver, bump manually!
-    {vsn, "5.0.21"},
+    {vsn, "5.0.22"},
     {modules, []},
     {registered, [emqx_management_sup]},
     {applications, [kernel, stdlib, emqx_plugins, minirest, emqx, emqx_ctl]},

apps/emqx_management/src/emqx_mgmt_api_api_keys.erl

@@ -18,6 +18,7 @@
 -behaviour(minirest_api).
 
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -export([api_spec/0, fields/1, paths/0, schema/1, namespace/0]).
 -export([api_key/2, api_key_by_name/2]).
@@ -36,14 +37,14 @@ schema("/api_key") ->
     #{
         'operationId' => api_key,
         get => #{
-            description => "Return api_key list",
+            description => ?DESC(api_key_list),
             tags => ?TAGS,
             responses => #{
                 200 => delete([api_secret], fields(app))
             }
         },
         post => #{
-            description => "Create new api_key",
+            description => ?DESC(create_new_api_key),
             tags => ?TAGS,
             'requestBody' => delete([created_at, api_key, api_secret], fields(app)),
             responses => #{
@@ -56,7 +57,7 @@ schema("/api_key/:name") ->
     #{
         'operationId' => api_key_by_name,
         get => #{
-            description => "Return the specific api_key",
+            description => ?DESC(get_api_key),
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],
             responses => #{
@@ -65,7 +66,7 @@ schema("/api_key/:name") ->
             }
         },
         put => #{
-            description => "Update the specific api_key",
+            description => ?DESC(update_api_key),
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],
             'requestBody' => delete([created_at, api_key, api_secret, name], fields(app)),
@@ -75,7 +76,7 @@ schema("/api_key/:name") ->
             }
         },
         delete => #{
-            description => "Delete the specific api_key",
+            description => ?DESC(delete_api_key),
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],
             responses => #{

apps/emqx_management/src/emqx_mgmt_api_clients.erl

@@ -20,6 +20,7 @@
 
 -include_lib("typerefl/include/types.hrl").
 -include_lib("emqx/include/emqx.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -include_lib("emqx/include/logger.hrl").
 
@@ -101,7 +102,7 @@ schema("/clients") ->
     #{
         'operationId' => clients,
         get => #{
-            description => <<"List clients">>,
+            description => ?DESC(list_clients),
             tags => ?TAGS,
             parameters => [
                 hoconsc:ref(emqx_dashboard_swagger, page),
@@ -214,7 +215,7 @@ schema("/clients/:clientid") ->
     #{
         'operationId' => client,
         get => #{
-            description => <<"Get clients info by client ID">>,
+            description => ?DESC(clients_info_from_id),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             responses => #{
@@ -225,7 +226,7 @@ schema("/clients/:clientid") ->
             }
         },
         delete => #{
-            description => <<"Kick out client by client ID">>,
+            description => ?DESC(kick_client_id),
             tags => ?TAGS,
             parameters => [
                 {clientid, hoconsc:mk(binary(), #{in => path})}
@@ -242,7 +243,7 @@ schema("/clients/:clientid/authorization/cache") ->
     #{
         'operationId' => authz_cache,
         get => #{
-            description => <<"Get client authz cache in the cluster.">>,
+            description => ?DESC(get_authz_cache),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             responses => #{
@@ -253,7 +254,7 @@ schema("/clients/:clientid/authorization/cache") ->
             }
         },
         delete => #{
-            description => <<"Clean client authz cache in the cluster.">>,
+            description => ?DESC(clean_authz_cache),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             responses => #{
@@ -268,7 +269,7 @@ schema("/clients/:clientid/subscriptions") ->
     #{
         'operationId' => subscriptions,
         get => #{
-            description => <<"Get client subscriptions">>,
+            description => ?DESC(get_client_subs),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             responses => #{
@@ -285,7 +286,7 @@ schema("/clients/:clientid/subscribe") ->
     #{
         'operationId' => subscribe,
         post => #{
-            description => <<"Subscribe">>,
+            description => ?DESC(subscribe),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             'requestBody' => hoconsc:mk(hoconsc:ref(?MODULE, subscribe)),
@@ -301,7 +302,7 @@ schema("/clients/:clientid/subscribe/bulk") ->
     #{
         'operationId' => subscribe_batch,
         post => #{
-            description => <<"Subscribe">>,
+            description => ?DESC(subscribe_g),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             'requestBody' => hoconsc:mk(hoconsc:array(hoconsc:ref(?MODULE, subscribe))),
@@ -317,7 +318,7 @@ schema("/clients/:clientid/unsubscribe") ->
     #{
         'operationId' => unsubscribe,
         post => #{
-            description => <<"Unsubscribe">>,
+            description => ?DESC(unsubscribe),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             'requestBody' => hoconsc:mk(hoconsc:ref(?MODULE, unsubscribe)),
@@ -333,7 +334,7 @@ schema("/clients/:clientid/unsubscribe/bulk") ->
     #{
         'operationId' => unsubscribe_batch,
         post => #{
-            description => <<"Unsubscribe">>,
+            description => ?DESC(unsubscribe_g),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             'requestBody' => hoconsc:mk(hoconsc:array(hoconsc:ref(?MODULE, unsubscribe))),
@@ -349,7 +350,7 @@ schema("/clients/:clientid/keepalive") ->
     #{
         'operationId' => set_keepalive,
         put => #{
-            description => <<"Set the online client keepalive by seconds">>,
+            description => ?DESC(set_keepalive_seconds),
             tags => ?TAGS,
             parameters => [{clientid, hoconsc:mk(binary(), #{in => path})}],
             'requestBody' => hoconsc:mk(hoconsc:ref(?MODULE, keepalive)),

apps/emqx_management/src/emqx_mgmt_api_cluster.erl

@@ -39,7 +39,7 @@ schema("/cluster") ->
     #{
         'operationId' => cluster_info,
         get => #{
-            description => "Get cluster info",
+            desc => ?DESC(get_cluster_info),
             tags => [<<"Cluster">>],
             responses => #{
                 200 => [
@@ -54,7 +54,7 @@ schema("/cluster/:node/invite") ->
     #{
         'operationId' => invite_node,
         put => #{
-            description => "Invite node to cluster",
+            desc => ?DESC(invite_node),
             tags => [<<"Cluster">>],
             parameters => [hoconsc:ref(node)],
             responses => #{
@@ -67,7 +67,7 @@ schema("/cluster/:node/force_leave") ->
     #{
         'operationId' => force_leave,
         delete => #{
-            description => "Force leave node from cluster",
+            desc => ?DESC(force_remove_node),
             tags => [<<"Cluster">>],
             parameters => [hoconsc:ref(node)],
             responses => #{

apps/emqx_management/src/emqx_mgmt_api_configs.erl

@@ -67,8 +67,7 @@ schema("/configs") ->
         'operationId' => configs,
         get => #{
             tags => ?TAGS,
-            description =>
-                <<"Get all the configurations of the specified node, including hot and non-hot updatable items.">>,
+            description => ?DESC(get_conf_node),
             parameters => [
                 {node,
                     hoconsc:mk(
@@ -77,8 +76,7 @@ schema("/configs") ->
                             in => query,
                             required => false,
                             example => <<"emqx@127.0.0.1">>,
-                            desc =>
-                                <<"Node's name: If you do not fill in the fields, this node will be used by default.">>
+                            description => ?DESC(node_name)
                         }
                     )}
             ],
@@ -95,12 +93,7 @@ schema("/configs_reset/:rootname") ->
         'operationId' => config_reset,
         post => #{
             tags => ?TAGS,
-            description =>
-                <<
-                    "Reset the config entry specified by the query string parameter `conf_path`.<br/>"
-                    "- For a config entry that has default value, this resets it to the default value;\n"
-                    "- For a config entry that has no default value, an error 400 will be returned"
-                >>,
+            description => ?DESC(rest_conf_query),
             %% We only return "200" rather than the new configs that has been changed, as
             %% the schema of the changed configs is depends on the request parameter
             %% `conf_path`, it cannot be defined here.
@@ -134,12 +127,12 @@ schema("/configs/global_zone") ->
         'operationId' => global_zone_configs,
         get => #{
             tags => ?TAGS,
-            description => <<"Get the global zone configs">>,
+            description => ?DESC(get_global_zone_configs),
             responses => #{200 => Schema}
         },
         put => #{
             tags => ?TAGS,
-            description => <<"Update globbal zone configs">>,
+            description => ?DESC(update_globar_zone_configs),
             'requestBody' => Schema,
             responses => #{
                 200 => Schema,
@@ -153,15 +146,15 @@ schema("/configs/limiter") ->
         'operationId' => limiter,
         get => #{
             tags => ?TAGS,
-            description => <<"Get the node-level limiter configs">>,
+            description => ?DESC(get_node_level_limiter_congigs),
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(emqx_limiter_schema, limiter)),
                 404 => emqx_dashboard_swagger:error_codes(['NOT_FOUND'], <<"config not found">>)
             }
         },
         put => #{
             tags => ?TAGS,
-            description => <<"Update the node-level limiter configs">>,
+            description => ?DESC(update_node_level_limiter_congigs),
             'requestBody' => hoconsc:mk(hoconsc:ref(emqx_limiter_schema, limiter)),
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(emqx_limiter_schema, limiter)),
@@ -172,27 +165,31 @@ schema("/configs/limiter") ->
     };
 schema(Path) ->
     {RootKey, {_Root, Schema}} = find_schema(Path),
+    GetDesc = iolist_to_binary([
+        <<"Get the sub-configurations under *">>,
+        RootKey,
+        <<"*">>
+    ]),
+    PutDesc = iolist_to_binary([
+        <<"Update the sub-configurations under *">>,
+        RootKey,
+        <<"*">>
+    ]),
     #{
         'operationId' => config,
         get => #{
             tags => ?TAGS,
-            description => iolist_to_binary([
-                <<"Get the sub-configurations under *">>,
-                RootKey,
-                <<"*">>
-            ]),
+            desc => GetDesc,
+            summary => GetDesc,
             responses => #{
                 200 => Schema,
                 404 => emqx_dashboard_swagger:error_codes(['NOT_FOUND'], <<"config not found">>)
             }
         },
         put => #{
             tags => ?TAGS,
-            description => iolist_to_binary([
-                <<"Update the sub-configurations under *">>,
-                RootKey,
-                <<"*">>
-            ]),
+            desc => PutDesc,
+            summary => PutDesc,
             'requestBody' => Schema,
             responses => #{
                 200 => Schema,