Merge pull request #9082 from HJianBo/update-api-docs

chore(i18n): enrich HTTP API desc

apps/emqx_authn/src/emqx_authn_api.erl

@@ -34,7 +34,7 @@
 % Swagger
 
 -define(API_TAGS_GLOBAL, [<<"Authentication">>]).
--define(API_TAGS_SINGLE, [<<"Listener authentication">>]).
+-define(API_TAGS_SINGLE, [<<"Listener Authentication">>]).
 
 -export([
     api_spec/0,

apps/emqx_authn/src/emqx_authn_user_import_api.erl

@@ -30,7 +30,7 @@
 
 % Swagger
 -define(API_TAGS_GLOBAL, [<<"Authentication">>]).
--define(API_TAGS_SINGLE, [<<"Listener authentication">>]).
+-define(API_TAGS_SINGLE, [<<"Listener Authentication">>]).
 
 -export([
     api_spec/0,

apps/emqx_auto_subscribe/src/emqx_auto_subscribe.app.src

@@ -1,7 +1,7 @@
 %% -*- mode: erlang -*-
 {application, emqx_auto_subscribe, [
     {description, "An OTP application"},
-    {vsn, "0.1.1"},
+    {vsn, "0.1.2"},
     {registered, []},
     {mod, {emqx_auto_subscribe_app, []}},
     {applications, [

apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl

@@ -44,14 +44,14 @@ schema("/mqtt/auto_subscribe") ->
         'operationId' => auto_subscribe,
         get => #{
             description => ?DESC(list_auto_subscribe_api),
-            tags => [<<"Auto subscribe">>],
+            tags => [<<"Auto Subscribe">>],
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe")
             }
         },
         put => #{
             description => ?DESC(update_auto_subscribe_api),
-            tags => [<<"Auto subscribe">>],
+            tags => [<<"Auto Subscribe">>],
             'requestBody' => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),
             responses => #{
                 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"),

apps/emqx_dashboard/src/emqx_dashboard_error_code_api.erl

@@ -51,7 +51,7 @@ schema("/error_codes") ->
         get => #{
             security => [],
             description => <<"API Error Codes">>,
-            tags => [<<"Error codes">>],
+            tags => [<<"Error Codes">>],
             responses => #{
                 200 => hoconsc:array(hoconsc:ref(?MODULE, error_code))
             }
@@ -63,7 +63,7 @@ schema("/error_codes/:code") ->
         get => #{
             security => [],
             description => <<"API Error Codes">>,
-            tags => [<<"Error codes">>],
+            tags => [<<"Error Codes">>],
             parameters => [
                 {code,
                     hoconsc:mk(hoconsc:enum(emqx_dashboard_error_code:all()), #{

apps/emqx_exhook/src/emqx_exhook.app.src

@@ -1,7 +1,7 @@
 %% -*- mode: erlang -*-
 {application, emqx_exhook, [
     {description, "EMQX Extension for Hook"},
-    {vsn, "5.0.4"},
+    {vsn, "5.0.5"},
     {modules, []},
     {registered, []},
     {mod, {emqx_exhook_app, []}},

apps/emqx_exhook/src/emqx_exhook_api.erl

@@ -41,7 +41,7 @@
 -import(hoconsc, [mk/1, mk/2, ref/1, enum/1, array/1, map/2]).
 -import(emqx_dashboard_swagger, [schema_with_example/2, error_codes/2]).
 
--define(TAGS, [<<"exhooks">>]).
+-define(TAGS, [<<"ExHook">>]).
 -define(NOT_FOURD, 'NOT_FOUND').
 -define(BAD_REQUEST, 'BAD_REQUEST').
 -define(BAD_RPC, 'BAD_RPC').

apps/emqx_gateway/i18n/emqx_gateway_api_authn_i18n.conf

@@ -2,70 +2,76 @@ emqx_gateway_api_authn {
 
     get_authn {
         desc {
-            en: """Get the gateway authentication"""
-            zh: """获取指定网关认证器"""
+            en: """Gets the configuration of the specified gateway authenticator.</br>
+Returns 404 when gateway or authentication is not enabled."""
+            zh: """获取指定网关认证器的配置
+当网关或认证未启用时，返回 404。"""
         }
     }
 
     update_authn {
         desc {
-            en: """Update authentication for the gateway"""
-            zh: """更新网关认证器"""
+            en: """Update the configuration of the specified gateway authenticator, or disable the authenticator."""
+            zh: """更新指定网关认证器的配置，或停用认证器。"""
         }
     }
 
     add_authn {
         desc {
-            en: """Add authentication for the gateway"""
-            zh: """为指定网关新增认证器"""
+            en: """Enables the authenticator for client authentication for the specified gateway. <\br>
+When the authenticator is not configured or turned off, all client connections are assumed to be allowed. <\br>
+Note: Only one authenticator is allowed to be enabled at a time in the gateway, rather than allowing multiple authenticators to be configured to form an authentication chain as in MQTT."""
+            zh: """为指定网关开启认证器实现客户端认证的功能。<\br>
+当未配置认证器或关闭认证器时，则认为允许所有客户端的连接。<\br>
+注：在网关中仅支持添加一个认证器，而不是像 MQTT 一样允许配置多个认证器构成认证链。"""
         }
     }
 
     delete_authn {
         desc {
-            en: """Remove the gateway authentication"""
-            zh: """删除指定网关的认证器"""
+            en: """Delete the authenticator of the specified gateway."""
+            zh: """删除指定网关的认证器。"""
         }
     }
 
     list_users {
         desc {
-            en: """Get the users for the authentication"""
+            en: """Get the users for the authenticator (only supported by <code>built_in_database</code>)."""
             zh: """获取用户列表（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     add_user {
         desc {
-            en: """Add user for the authentication"""
+            en: """Add user for the authenticator (only supports built_in_database)."""
             zh: """添加用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     get_user {
         desc {
-            en: """Get user info from the gateway authentication"""
+            en: """Get user info from the gateway authenticator (only supports built_in_database)"""
             zh: """获取用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     update_user {
         desc {
-            en: """Update the user info for the gateway authentication"""
+            en: """Update the user info for the gateway authenticator (only supports built_in_database)"""
             zh: """更新用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     delete_user {
         desc {
-            en: """Delete the user for the gateway authentication"""
+            en: """Delete the user for the gateway authenticator (only supports built_in_database)"""
             zh: """删除用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     import_users {
         desc {
-            en: """Import users into the gateway authentication"""
+            en: """Import users into the gateway authenticator (only supports built_in_database)"""
             zh: """导入用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
@@ -79,8 +85,8 @@ emqx_gateway_api_authn {
 
     like_user_id {
         desc {
-            en: """Fuzzy search by user_id (username or clientid)"""
-            zh: """用户 ID （username 或 clientid）模糊搜索"""
+            en: """Fuzzy search using user ID (username or clientid), only supports search by substring."""
+            zh: """使用用户 ID （username 或 clientid）模糊搜索，仅支持按子串的方式进行搜索。"""
         }
     }
 
@@ -90,5 +96,4 @@ emqx_gateway_api_authn {
             zh: """是否是超级用户"""
         }
     }
-
 }

apps/emqx_gateway/i18n/emqx_gateway_api_i18n.conf

@@ -2,15 +2,17 @@ emqx_gateway_api {
 
     list_gateway {
         desc {
-            en: """Get gateway list"""
-            zh: """获取网关列表"""
+            en: """This API returns an overview info for the specified or all gateways.
+including current running status, number of connections, listener status, etc."""
+            zh: """该接口会返回指定或所有网关的概览状态，
+包括当前状态、连接数、监听器状态等。"""
         }
     }
 
     enable_gateway {
         desc {
-            en: """Enable a gateway"""
-            zh: """启用某网关"""
+            en: """Enable a gateway by confs."""
+            zh: """使用配置启动某一网关。"""
         }
     }
 
@@ -23,15 +25,17 @@ emqx_gateway_api {
 
     delete_gateway {
         desc {
-            en: """Delete/Unload the gateway"""
-            zh: """删除/禁用某网关"""
+            en: """Unload the specified gateway"""
+            zh: """停用指定网关"""
         }
     }
 
     update_gateway {
         desc {
-            en: """Update the gateway configurations/status"""
-            zh: """更新网关配置或启用状态"""
+            en: """Update the gateway basic configurations and running status.</br>
+Note: The Authentication and Listener configurations should be updated by other special APIs. """
+            zh: """更新指定网关的基础配置、和启用的状态。</br>
+注：认证、和监听器的配置更新需参考对应的 API 接口。"""
         }
     }
 
@@ -42,13 +46,33 @@ emqx_gateway_api {
         }
     }
 
+    gateway_name_in_qs {
+        desc {
+            en: """Gateway Name.</br>
+It's enum with `stomp`, `mqttsn`, `coap`, `lwm2m`, `exproto`
+"""
+            zh: """网关名称.</br>
+可取值为 `stomp`、`mqttsn`、`coap`、`lwm2m`、`exproto`
+"""
+        }
+    }
+
     gateway_status {
         desc {
-            en: """Gateway Status"""
+            en: """Gateway status"""
             zh: """网关启用状态"""
         }
     }
 
+    gateway_status_in_qs {
+        desc {
+            en: """Filter gateways by status.</br>
+It is enum with `running`, `stopped`, `unloaded`"""
+            zh: """通过网关状态筛选</br>
+可选值为 `running`、`stopped`、`unloaded`"""
+        }
+    }
+
     gateway_created_at {
         desc {
             en: """The Gateway created datetime"""

apps/emqx_gateway/i18n/emqx_gateway_api_listeners_i18n.conf

@@ -2,105 +2,109 @@ emqx_gateway_api_listeners {
 
     list_listeners {
         desc {
-            en: """Get the gateway listeners"""
-            zh: """获取网关监听器列表"""
+            en: """Gets a list of gateway listeners. This interface returns all the configs of the listener (including the authenticator on that listener), as well as the status of that listener running in the cluster."""
+            zh: """获取网关监听器列表。该接口会返回监听器所有的配置（包括该监听器上的认证器），同时也会返回该监听器在集群中运行的状态。"""
         }
     }
 
     add_listener {
         desc {
-            en: """Create the gateway listener"""
-            zh: """为指定网关添加监听器"""
+            en: """Create the gateway listener.</br>
+Note: For listener types not supported by a gateway, this API returns `400: BAD_REQUEST`."""
+            zh: """为指定网关添加监听器。</br>
+注：对于某网关不支持的监听器类型，该接口会返回 `400: BAD_REQUEST`。"""
         }
     }
 
     get_listener {
         desc {
-            en: """Get the gateway listener configurations"""
-            zh: """获取指定监听器信息"""
+            en: """Get the gateway listener configs"""
+            zh: """获取指定网关监听器的配置。"""
         }
     }
 
     delete_listener {
         desc {
-            en: """Delete the gateway listener"""
-            zh: """删除监听器"""
+            en: """Delete the gateway listener. All connected clients under the deleted listener will be disconnected."""
+            zh: """删除指定监听器。被删除的监听器下所有已连接的客户端都会离线。"""
         }
     }
 
     update_listener {
         desc {
-            en: """Update the gateway listener"""
-            zh: """更新监听器"""
+            en: """Update the gateway listener. The listener being updated performs a restart and all clients connected to that listener will be disconnected."""
+            zh: """更新某网关监听器的配置。被更新的监听器会执行重启，所有已连接到该监听器上的客户端都会被断开。"""
         }
     }
 
     get_listener_authn {
         desc {
-            en: """Get the listener's authentication info"""
-            zh: """获取监听器的认证器信息"""
+            en: """Get the listener's authenticator configs."""
+            zh: """获取监听器的认证器配置。"""
         }
     }
 
     add_listener_authn {
         desc {
-            en: """Add authentication for the listener"""
-            zh: """为指定监听器添加认证器"""
+            en: """Enable authenticator for specified listener for client authentication.</br>
+When authenticator is enabled for a listener, all clients connecting to that listener will use that authenticator for authentication."""
+            zh: """为指定监听器开启认证器以实现客户端认证的能力。</br>
+当某一监听器开启认证后，所有连接到该监听器的客户端会使用该认证器进行认证。"""
         }
     }
 
     update_listener_authn {
         desc {
-            en: """Update authentication for the listener"""
-            zh: """更新指定监听上的认证器配置"""
+            en: """Update authenticator configs for the listener, or disable/enable it."""
+            zh: """更新指定监听器的认证器配置，或停用/启用该认证器。"""
         }
     }
 
     delete_listener_authn {
         desc {
-            en: """Remove authentication for the listener"""
-            zh: """为指定监听器移除认证器"""
+            en: """Remove authenticator for the listener."""
+            zh: """移除指定监听器的认证器。"""
         }
     }
 
     list_users {
         desc {
-            en: """Get the users for the authentication"""
+            en: """Get the users for the authenticator (only supported by <code>built_in_database</code>)"""
             zh: """获取用户列表（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     add_user {
         desc {
-            en: """Add user for the authentication"""
+            en: """Add user for the authenticator (only supports built_in_database)"""
             zh: """添加用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     get_user {
         desc {
-            en: """Get user info from the gateway authentication"""
+            en: """Get user info from the gateway authenticator (only supports built_in_database)"""
             zh: """获取用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     update_user {
         desc {
-            en: """Update the user info for the gateway authentication"""
+            en: """Update the user info for the gateway authenticator (only supports built_in_database)"""
             zh: """更新用户信息（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     delete_user {
         desc {
-            en: """Delete the user for the gateway authentication"""
+            en: """Delete the user for the gateway authenticator (only supports built_in_database)"""
             zh: """删除用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
 
     import_users {
         desc {
-            en: """Import users into the gateway authentication"""
+            en: """Import users into the gateway authenticator (only supports built_in_database)"""
             zh: """导入用户（仅支持 built_in_database 类型的认证器）"""
         }
     }
@@ -139,5 +143,4 @@ emqx_gateway_api_listeners {
             zh: """当前连接数"""
         }
     }
-
 }

apps/emqx_gateway/src/coap/emqx_coap_api.erl

@@ -48,8 +48,9 @@ schema(?PREFIX ++ "/request") ->
     #{
         operationId => request,
         post => #{
-            tags => [<<"CoAP">>],
+            tags => [<<"Gateways">>],
             desc => ?DESC(send_coap_request),
+            summary => <<"Send a Request to a Client">>,
             parameters => request_parameters(),
             requestBody => request_body(),
             responses => #{

apps/emqx_gateway/src/emqx_gateway_api.erl

@@ -164,7 +164,9 @@ schema("/gateways") ->
         'operationId' => gateway,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_gateway),
+                summary => <<"List All Gateways">>,
                 parameters => params_gateway_status_in_qs(),
                 responses =>
                     ?STANDARD_RESP(
@@ -178,7 +180,9 @@ schema("/gateways") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(enable_gateway),
+                summary => <<"Enable a Gateway">>,
                 %% TODO: distinguish create & response swagger schema
                 'requestBody' => schema_gateways_conf(),
                 responses =>
@@ -190,21 +194,27 @@ schema("/gateways/:name") ->
         'operationId' => gateway_insta,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_gateway),
+                summary => <<"Get the Gateway">>,
                 parameters => params_gateway_name_in_path(),
                 responses =>
                     ?STANDARD_RESP(#{200 => schema_gateways_conf()})
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_gateway),
+                summary => <<"Unload the gateway">>,
                 parameters => params_gateway_name_in_path(),
                 responses =>
                     ?STANDARD_RESP(#{204 => <<"Deleted">>})
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_gateway),
+                summary => <<"Update the gateway confs">>,
                 parameters => params_gateway_name_in_path(),
                 'requestBody' => schema_update_gateways_conf(),
                 responses =>
@@ -224,8 +234,8 @@ params_gateway_name_in_path() ->
                 binary(),
                 #{
                     in => path,
-                    desc => ?DESC(gateway_name),
-                    example => <<"">>
+                    desc => ?DESC(gateway_name_in_qs),
+                    example => <<"stomp">>
                 }
             )}
     ].
@@ -239,7 +249,7 @@ params_gateway_status_in_qs() ->
                 #{
                     in => query,
                     required => false,
-                    desc => ?DESC(gateway_status),
+                    desc => ?DESC(gateway_status_in_qs),
                     example => <<"">>
                 }
             )}

apps/emqx_gateway/src/emqx_gateway_api_authn.erl

@@ -75,6 +75,7 @@ authn(get, #{bindings := #{name := Name0}}) ->
             Authn -> {200, Authn}
         catch
             error:{config_not_found, _} ->
+                %% FIXME: should return 404?
                 {204}
         end
     end);
@@ -181,19 +182,23 @@ schema("/gateways/:name/authentication") ->
         'operationId' => authn,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_authn),
+                summary => <<"Get Authenticator Configuration">>,
                 parameters => params_gateway_name_in_path(),
                 responses =>
                     ?STANDARD_RESP(
                         #{
                             200 => schema_authn(),
-                            204 => <<"Authentication does not initiated">>
+                            204 => <<"Authenticator doesn't initiated">>
                         }
                     )
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_authn),
+                summary => <<"Update Authenticator Configuration">>,
                 parameters => params_gateway_name_in_path(),
                 'requestBody' => schema_authn(),
                 responses =>
@@ -201,7 +206,9 @@ schema("/gateways/:name/authentication") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_authn),
+                summary => <<"Create an Authenticator for a Gateway">>,
                 parameters => params_gateway_name_in_path(),
                 'requestBody' => schema_authn(),
                 responses =>
@@ -209,7 +216,9 @@ schema("/gateways/:name/authentication") ->
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_authn),
+                summary => <<"Delete the Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path(),
                 responses =>
                     ?STANDARD_RESP(#{204 => <<"Deleted">>})
@@ -220,7 +229,9 @@ schema("/gateways/:name/authentication/users") ->
         'operationId' => users,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_users),
+                summary => <<"List users for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_paging_in_qs() ++
                     params_fuzzy_in_qs(),
@@ -236,7 +247,9 @@ schema("/gateways/:name/authentication/users") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_user),
+                summary => <<"Add User for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path(),
                 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                     ref(emqx_authn_api, request_user_create),
@@ -258,7 +271,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
         'operationId' => users_insta,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_user),
+                summary => <<"Get User Info for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_userid_in_path(),
                 responses =>
@@ -273,7 +288,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_user),
+                summary => <<"Update User Info for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_userid_in_path(),
                 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@@ -292,7 +309,9 @@ schema("/gateways/:name/authentication/users/:uid") ->
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_user),
+                summary => <<"Delete User for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_userid_in_path(),
                 responses =>
@@ -311,8 +330,8 @@ params_gateway_name_in_path() ->
                 binary(),
                 #{
                     in => path,
-                    desc => ?DESC(emqx_gateway_api, gateway_name),
-                    example => <<"">>
+                    desc => ?DESC(emqx_gateway_api, gateway_name_in_qs),
+                    example => <<"stomp">>
                 }
             )}
     ].
@@ -325,7 +344,7 @@ params_userid_in_path() ->
                 #{
                     in => path,
                     desc => ?DESC(user_id),
-                    example => <<"">>
+                    example => <<"test_username">>
                 }
             )}
     ].
@@ -343,7 +362,7 @@ params_fuzzy_in_qs() ->
                     in => query,
                     required => false,
                     desc => ?DESC(like_user_id),
-                    example => <<"username">>
+                    example => <<"test_">>
                 }
             )},
         {is_superuser,

apps/emqx_gateway/src/emqx_gateway_api_authn_user_import.erl

@@ -122,7 +122,9 @@ schema("/gateways/:name/authentication/import_users") ->
         'operationId' => import_users,
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(emqx_gateway_api_authn, import_users),
+                summary => <<"Import Users">>,
                 parameters => params_gateway_name_in_path(),
                 'requestBody' => emqx_dashboard_swagger:file_schema(filename),
                 responses =>
@@ -134,7 +136,9 @@ schema("/gateways/:name/listeners/:id/authentication/import_users") ->
         'operationId' => import_listener_users,
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(emqx_gateway_api_listeners, import_users),
+                summary => <<"Import Users">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 'requestBody' => emqx_dashboard_swagger:file_schema(filename),
@@ -144,6 +148,7 @@ schema("/gateways/:name/listeners/:id/authentication/import_users") ->
     };
 schema(Path) ->
     emqx_gateway_utils:make_compatible_schema(Path, fun schema/1).
+
 %%--------------------------------------------------------------------
 %% params defines
 %%--------------------------------------------------------------------
@@ -155,7 +160,7 @@ params_gateway_name_in_path() ->
                 binary(),
                 #{
                     in => path,
-                    desc => ?DESC(emqx_gateway_api, gateway_name),
+                    desc => ?DESC(emqx_gateway_api, gateway_name_in_qs),
                     example => <<"stomp">>
                 }
             )}

apps/emqx_gateway/src/emqx_gateway_api_clients.erl

@@ -467,7 +467,9 @@ schema("/gateways/:name/clients") ->
         'operationId' => clients,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_clients),
+                summary => <<"List Gateway's Clients">>,
                 parameters => params_client_query(),
                 responses =>
                     ?STANDARD_RESP(#{200 => schema_client_list()})
@@ -478,14 +480,18 @@ schema("/gateways/:name/clients/:clientid") ->
         'operationId' => clients_insta,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_client),
+                summary => <<"Get Client Info">>,
                 parameters => params_client_insta(),
                 responses =>
                     ?STANDARD_RESP(#{200 => schema_client()})
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(kick_client),
+                summary => <<"Kick out Client">>,
                 parameters => params_client_insta(),
                 responses =>
                     ?STANDARD_RESP(#{204 => <<"Kicked">>})
@@ -496,7 +502,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
         'operationId' => subscriptions,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_subscriptions),
+                summary => <<"List Client's Subscription">>,
                 parameters => params_client_insta(),
                 responses =>
                     ?STANDARD_RESP(
@@ -510,7 +518,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_subscription),
+                summary => <<"Add Subscription for Client">>,
                 parameters => params_client_insta(),
                 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                     ref(subscription),
@@ -532,7 +542,9 @@ schema("/gateways/:name/clients/:clientid/subscriptions/:topic") ->
         'operationId' => subscriptions,
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_subscription),
+                summary => <<"Delete Client's Subscription">>,
                 parameters => params_topic_name_in_path() ++ params_client_insta(),
                 responses =>
                     ?STANDARD_RESP(#{204 => <<"Unsubscribed">>})

apps/emqx_gateway/src/emqx_gateway_api_listeners.erl

@@ -358,7 +358,9 @@ schema("/gateways/:name/listeners") ->
         'operationId' => listeners,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_listeners),
+                summary => <<"List All Listeners">>,
                 parameters => params_gateway_name_in_path(),
                 responses =>
                     ?STANDARD_RESP(
@@ -372,7 +374,9 @@ schema("/gateways/:name/listeners") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_listener),
+                summary => <<"Add a Listener">>,
                 parameters => params_gateway_name_in_path(),
                 %% XXX: How to distinguish the different listener supported by
                 %% different types of gateways?
@@ -396,7 +400,9 @@ schema("/gateways/:name/listeners/:id") ->
         'operationId' => listeners_insta,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_listener),
+                summary => <<"Get the Listener Configs">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 responses =>
@@ -411,7 +417,9 @@ schema("/gateways/:name/listeners/:id") ->
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_listener),
+                summary => <<"Delete the Listener">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 responses =>
@@ -419,7 +427,9 @@ schema("/gateways/:name/listeners/:id") ->
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_listener),
+                summary => <<"Update the Listener Configs">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@@ -442,7 +452,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
         'operationId' => listeners_insta_authn,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_listener_authn),
+                summary => <<"Get the Listener's Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 responses =>
@@ -455,7 +467,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_listener_authn),
+                summary => <<"Create an Authenticator for a Listener">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 'requestBody' => schema_authn(),
@@ -464,7 +478,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_listener_authn),
+                summary => <<"Update the Listener Authenticator configs">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 'requestBody' => schema_authn(),
@@ -473,7 +489,9 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_listener_authn),
+                summary => <<"Delete the Listener's Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 responses =>
@@ -485,7 +503,9 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
         'operationId' => users,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(list_users),
+                summary => <<"List Authenticator's Users">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path() ++
                     params_paging_in_qs(),
@@ -501,7 +521,9 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
             },
         post =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(add_user),
+                summary => <<"Add User for an Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path(),
                 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@@ -524,7 +546,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
         'operationId' => users_insta,
         get =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(get_user),
+                summary => <<"Get User Info">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path() ++
                     params_userid_in_path(),
@@ -540,7 +564,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
             },
         put =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(update_user),
+                summary => <<"Update User Info">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path() ++
                     params_userid_in_path(),
@@ -560,7 +586,9 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
             },
         delete =>
             #{
+                tags => [<<"Gateways">>],
                 desc => ?DESC(delete_user),
+                summary => <<"Delete User">>,
                 parameters => params_gateway_name_in_path() ++
                     params_listener_id_in_path() ++
                     params_userid_in_path(),
@@ -570,6 +598,7 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
     };
 schema(Path) ->
     emqx_gateway_utils:make_compatible_schema(Path, fun schema/1).
+
 %%--------------------------------------------------------------------
 %% params defines
 
@@ -580,8 +609,8 @@ params_gateway_name_in_path() ->
                 binary(),
                 #{
                     in => path,
-                    desc => ?DESC(emqx_gateway_api, gateway_name),
-                    example => <<"">>
+                    desc => ?DESC(emqx_gateway_api, gateway_name_in_qs),
+                    example => <<"stomp">>
                 }
             )}
     ].

apps/emqx_gateway/src/lwm2m/emqx_lwm2m_api.erl

@@ -45,8 +45,9 @@ schema(?PATH("/lookup")) ->
     #{
         'operationId' => lookup,
         get => #{
-            tags => [<<"LwM2M">>],
+            tags => [<<"Gateways">>],
             desc => ?DESC(lookup_resource),
+            summary => <<"List Client's Resources">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@@ -69,8 +70,9 @@ schema(?PATH("/observe")) ->
     #{
         'operationId' => observe,
         post => #{
-            tags => [<<"LwM2M">>],
+            tags => [<<"Gateways">>],
             desc => ?DESC(observe_resource),
+            summary => <<"Observe a Resource">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@@ -87,8 +89,9 @@ schema(?PATH("/read")) ->
     #{
         'operationId' => read,
         post => #{
-            tags => [<<"LwM2M">>],
+            tags => [<<"Gateways">>],
             desc => ?DESC(read_resource),
+            summary => <<"Read Value from a Resource Path">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}
@@ -104,7 +107,8 @@ schema(?PATH("/write")) ->
         'operationId' => write,
         post => #{
             desc => ?DESC(write_resource),
-            tags => [<<"LwM2M">>],
+            tags => [<<"Gateways">>],
+            summary => <<"Write a Value to Resource Path">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},

apps/emqx_management/i18n/emqx_mgmt_api_alarms_i18n.conf

@@ -2,78 +2,82 @@ emqx_mgmt_api_alarms {
 
     list_alarms_api {
         desc {
-            en: """List alarms"""
-            zh: """列出告警，获取告警列表"""
+            en: """List currently activated alarms or historical alarms, determined by query parameters."""
+            zh: """列出当前激活的告警或历史告警，由查询参数决定。"""
         }
     }
 
     delete_alarms_api {
         desc {
-            en: """Remove all deactivated alarms"""
-            zh: """删除所有历史告警（非活跃告警）"""
+            en: """Remove all historical alarms."""
+            zh: """删除所有历史告警。"""
         }
     }
 
     delete_alarms_api_response204 {
         desc {
-            en: """Remove all deactivated alarms ok"""
-            zh: """删除所有历史告警（非活跃告警）成功"""
+            en: """Historical alarms have been cleared successfully."""
+            zh: """历史告警已成功清除。"""
         }
     }
 
     get_alarms_qs_activated {
         desc {
-            en: """Activate alarms, or deactivate alarms. Default is false"""
-            zh: """活跃中的告警，或历史告警（非活跃告警），默认为 false"""
+            en: """It is used to specify the alarm type of the query.
+When true, it returns the currently activated alarm,
+and when it is false, it returns the historical alarm.
+The default is false."""
+            zh: """用于指定查询的告警类型，
+为 true 时返回当前激活的告警，为 false 时返回历史告警，默认为 false。"""
         }
     }
 
     node {
         desc {
-            en: """Alarm in node"""
-            zh: """告警节点名称"""
+            en: """The name of the node that triggered this alarm."""
+            zh: """触发此告警的节点名称。"""
         }
     }
 
     name {
         desc {
-            en: """Alarm name"""
-            zh: """告警名称"""
+            en: """Alarm name, used to distinguish different alarms."""
+            zh: """告警名称，用于区分不同的告警。"""
         }
     }
 
     message {
         desc {
-            en: """Alarm readable information"""
-            zh: """告警信息"""
+            en: """Alarm message, which describes the alarm content in a human-readable format."""
+            zh: """告警消息，以人类可读的方式描述告警内容。"""
         }
     }
 
     details {
         desc {
-            en: """Alarm details information"""
-            zh: """告警详细信息"""
+            en: """Alarm details, provides more alarm information, mainly for program processing."""
+            zh: """告警详情，提供了更多的告警信息，主要提供给程序处理。"""
         }
     }
 
     duration {
         desc {
-            en: """Alarms duration time; UNIX time stamp, millisecond"""
-            zh: """告警持续时间，单位：毫秒"""
+            en: """Indicates how long the alarm has lasted, in milliseconds."""
+            zh: """表明告警已经持续了多久，单位：毫秒。"""
         }
     }
 
     activate_at {
         desc {
-            en: """Alarms activate time, RFC 3339"""
-            zh: """告警开始时间，使用 rfc3339 标准时间格式"""
+            en: """Alarm start time, using rfc3339 standard time format."""
+            zh: """告警开始时间，使用 rfc3339 标准时间格式。"""
         }
     }
 
     deactivate_at {
         desc {
-            en: """Alarms deactivate time, RFC 3339"""
-            zh: """告警结束时间，使用 rfc3339 标准时间格式"""
+            en: """Alarm end time, using rfc3339 standard time format."""
+            zh: """告警结束时间，使用 rfc3339 标准时间格式。"""
         }
     }
 

apps/emqx_management/i18n/emqx_mgmt_api_banned_i18n.conf

@@ -2,112 +2,97 @@ emqx_mgmt_api_banned {
 
     list_banned_api {
         desc {
-            en: """List banned."""
-            zh: """列出黑名单"""
-        }
-        label {
-            en: """List Banned"""
-            zh: """列出黑名单"""
+            en: """List all currently banned client IDs, usernames and IP addresses."""
+            zh: """列出目前所有被封禁的客户端 ID、用户名和 IP 地址。"""
         }
     }
 
     create_banned_api {
         desc {
-            en: """Create banned."""
-            zh: """创建黑名单"""
+            en: """Add a client ID, username or IP address to the blacklist."""
+            zh: """添加一个客户端 ID、用户名或者 IP 地址到黑名单。"""
         }
     }
 
     create_banned_api_response400 {
         desc {
-            en: """Banned already existed, or bad args."""
-            zh: """黑名单已存在，或参数格式有错误"""
+            en: """Bad request, possibly due to wrong parameters or the existence of a banned object."""
+            zh: """错误的请求，可能是参数错误或封禁对象已存在等原因。"""
         }
     }
 
     delete_banned_api {
         desc {
-            en: """Delete banned"""
-            zh: """删除黑名单"""
+            en: """Remove a client ID, username or IP address from the blacklist."""
+            zh: """将一个客户端 ID、用户名或者 IP 地址从黑名单中删除。"""
         }
     }
 
     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: """列出黑名单"""
+            en: """The banned object was not found in the blacklist."""
+            zh: """未在黑名单中找到该封禁对象。"""
         }
     }
 
     as {
         desc {
-            en: """Banned type clientid, username, peerhost"""
-            zh: """黑名单类型，可选 clientid、username、peerhost"""
+            en: """Ban method, which can be client ID, username or IP address."""
+            zh: """封禁方式，可以通过客户端 ID、用户名或者 IP 地址等方式进行封禁。"""
         }
         label {
-            en: """Banned Type"""
-            zh: """黑名单类型"""
+            en: """Ban Method"""
+            zh: """封禁方式"""
         }
     }
     who {
         desc {
-            en: """Client info as banned type"""
-            zh: """设备信息"""
+            en: """Ban object, specific client ID, username or IP address."""
+            zh: """封禁对象，具体的客户端 ID、用户名或者 IP 地址。"""
         }
         label {
-            en: """Banned Info"""
-            zh: """黑名单信息"""
+            en: """Ban Object"""
+            zh: """封禁对象"""
         }
     }
     by {
         desc {
-            en: """Commander"""
-            zh: """黑名单创建者"""
+            en: """Initiator of the ban."""
+            zh: """封禁的发起者。"""
         }
         label {
-            en: """Commander"""
-            zh: """黑名单创建者"""
+            en: """Ban Initiator"""
+            zh: """封禁发起者"""
         }
     }
     reason {
         desc {
-            en: """Banned reason"""
-            zh: """黑名单创建原因"""
+            en: """Ban reason, record the reason why the current object was banned."""
+            zh: """封禁原因，记录当前对象被封禁的原因。"""
         }
         label {
-            en: """Reason"""
-            zh: """原因"""
+            en: """Ban Reason"""
+            zh: """封禁原因"""
         }
     }
     at {
         desc {
-            en: """Create banned time, rfc3339, now if not specified"""
-            zh: """黑名单创建时间，默认为当前"""
+            en: """The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated."""
+            zh: """封禁的起始时间，格式为 rfc3339，默认为发起操作的时间。"""
         }
         label {
-            en: """Create banned time"""
-            zh: """黑名单创建时间"""
+            en: """Ban Time"""
+            zh: """封禁时间"""
         }
     }
     until {
         desc {
-            en: """Cancel banned time, rfc3339, now + 5 minute if not specified"""
-            zh: """黑名单结束时间，默认为创建时间 + 5 分钟"""
+            en: """The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 5 minutes."""
+            zh: """封禁的结束时间，式为 rfc3339，默认为发起操作的时间 + 5 分钟。"""
         }
         label {
-            en: """Cancel banned time"""
-            zh: """黑名单结束时间"""
+            en: """Ban End Time"""
+            zh: """封禁结束时间"""
         }
     }
 }

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.5"},
+    {vsn, "5.0.6"},
     {modules, []},
     {registered, [emqx_management_sup]},
     {applications, [kernel, stdlib, emqx_plugins, minirest, emqx]},

apps/emqx_management/src/emqx_mgmt_api_app.erl

@@ -22,7 +22,7 @@
 -export([api_spec/0, fields/1, paths/0, schema/1, namespace/0]).
 -export([api_key/2, api_key_by_name/2]).
 -export([validate_name/1]).
--define(TAGS, [<<"API keys">>]).
+-define(TAGS, [<<"API Keys">>]).
 
 namespace() -> "api_key".
 

apps/emqx_management/src/emqx_mgmt_api_status.erl

@@ -20,6 +20,13 @@
     path/0
 ]).
 
+%% Note: Because swagger now requires an HTTP prefix (e.g. /api/v5),
+%% but the `/status` does not require this fixed prefix.
+%%
+%% Changing the swagger framework was too big, so we implemented the `/status`
+%% in a simple way first
+%%
+%% XXX: So the HTTP API docs generated by swagger can not find this API now
 path() ->
     "/status".
 

apps/emqx_management/src/emqx_mgmt_api_sys.erl

@@ -31,7 +31,7 @@
 
 -export([sys/2]).
 
--define(TAGS, [<<"System topics">>]).
+-define(TAGS, [<<"System Topics">>]).
 
 namespace() -> "sys".
 

apps/emqx_slow_subs/src/emqx_slow_subs_api.erl

@@ -25,7 +25,7 @@
 -export([api_spec/0, paths/0, schema/1, fields/1, namespace/0]).
 
 -export([slow_subs/2, get_history/0, settings/2]).
--define(TAGS, [<<"Slow subscriptions">>]).
+-define(TAGS, [<<"Slow Subscriptions">>]).
 
 -import(hoconsc, [mk/2, ref/1, ref/2]).
 -import(emqx_mgmt_util, [bad_request/0]).

apps/emqx_statsd/i18n/emqx_statsd_api_i18n.conf

@@ -0,0 +1,16 @@
+emqx_statsd_api {
+
+  get_statsd_config_api {
+    desc {
+      en: """List the configuration of StatsD metrics collection and push service."""
+      zh: """列出 StatsD 指标采集和推送服务的的配置。"""
+    }
+  }
+
+  update_statsd_config_api {
+    desc {
+      en: """Update the configuration of StatsD metrics collection and push service."""
+      zh: """更新 StatsD 指标采集和推送服务的配置。"""
+    }
+  }
+}

apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf

@@ -1,9 +1,23 @@
 emqx_statsd_schema {
 
+  get_statsd_config_api {
+    desc {
+      en: """List the configuration of StatsD metrics collection and push service."""
+      zh: """列出 StatsD 指标采集和推送服务的的配置。"""
+    }
+  }
+
+  update_statsd_config_api {
+    desc {
+      en: """Update the configuration of StatsD metrics collection and push service."""
+      zh: """更新 StatsD 指标采集和推送服务的配置。"""
+    }
+  }
+
   statsd {
     desc {
-      en: """Settings for reporting metrics to StatsD"""
-      zh: """StatsD 监控数据推送"""
+      en: """StatsD metrics collection and push configuration."""
+      zh: """StatsD 指标采集与推送配置。"""
     }
     label {
       en: """StatsD"""
@@ -13,29 +27,29 @@ emqx_statsd_schema {
 
   server {
     desc {
-      en: """URL of StatsD server"""
-      zh: """StatsD 服务器地址"""
+      en: """StatsD server address."""
+      zh: """StatsD 服务器地址。"""
     }
   }
 
   sample_interval {
     desc {
-      en: """Data collection interval."""
-      zh: """数据收集间隔"""
+      en: """The sampling interval for metrics."""
+      zh: """指标的采样间隔。"""
     }
   }
 
   flush_interval {
     desc {
-      en: """Data reporting interval."""
-      zh: """数据推送间隔"""
+      en: """The push interval for metrics."""
+      zh: """指标的推送间隔。"""
     }
   }
 
   enable {
     desc {
-      en: """Turn StatsD data pushing on or off"""
-      zh: """开启或关闭 StatsD 数据推送"""
+      en: """Enable or disable StatsD metrics collection and push service."""
+      zh: """启用或禁用 StatsD 指标采集和推送服务。"""
     }
   }
 }

apps/emqx_statsd/src/emqx_statsd_api.erl

@@ -20,6 +20,7 @@
 
 -include("emqx_statsd.hrl").
 
+-include_lib("hocon/include/hoconsc.hrl").
 -include_lib("typerefl/include/types.hrl").
 
 -import(hoconsc, [mk/2, ref/2]).
@@ -48,14 +49,14 @@ schema("/statsd") ->
         'operationId' => statsd,
         get =>
             #{
-                description => <<"Get statsd config">>,
+                description => ?DESC(get_statsd_config_api),
                 tags => ?API_TAG_STATSD,
                 responses =>
                     #{200 => statsd_config_schema()}
             },
         put =>
             #{
-                description => <<"Set statsd config">>,
+                description => ?DESC(update_statsd_config_api),
                 tags => ?API_TAG_STATSD,
                 'requestBody' => statsd_config_schema(),
                 responses =>