Merge pull request #9269 from zmstone/1031-docs-re-group-gateway-api-tags

docs: re-group api tags for gateway apps

apps/emqx_gateway/src/coap/emqx_coap_api.erl

@@ -29,6 +29,7 @@
 -export([request/2]).
 
 -define(PREFIX, "/gateways/coap/clients/:clientid").
+-define(TAGS, [<<"CoAP Gateways">>]).
 
 -import(hoconsc, [mk/2, enum/1]).
 -import(emqx_dashboard_swagger, [error_codes/2]).
@@ -48,7 +49,7 @@ schema(?PREFIX ++ "/request") ->
     #{
         operationId => request,
         post => #{
-            tags => [<<"Gateways">>],
+            tags => ?TAGS,
             desc => ?DESC(send_coap_request),
             summary => <<"Send a Request to a Client">>,
             parameters => request_parameters(),

apps/emqx_gateway/src/emqx_gateway_api.erl

@@ -54,6 +54,7 @@
 ]).
 
 -define(KNOWN_GATEWAY_STATUSES, [<<"running">>, <<"stopped">>, <<"unloaded">>]).
+-define(TAGS, [<<"Gateways">>]).
 
 %%--------------------------------------------------------------------
 %% minirest behaviour callbacks
@@ -176,7 +177,7 @@ schema("/gateways") ->
         'operationId' => gateway,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_gateway),
                 summary => <<"List All Gateways">>,
                 parameters => params_gateway_status_in_qs(),
@@ -192,7 +193,7 @@ schema("/gateways") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(enable_gateway),
                 summary => <<"Enable a Gateway">>,
                 %% TODO: distinguish create & response swagger schema
@@ -206,7 +207,7 @@ schema("/gateways/:name") ->
         'operationId' => gateway_insta,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_gateway),
                 summary => <<"Get the Gateway">>,
                 parameters => params_gateway_name_in_path(),
@@ -215,7 +216,7 @@ schema("/gateways/:name") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_gateway),
                 summary => <<"Unload the gateway">>,
                 parameters => params_gateway_name_in_path(),
@@ -224,7 +225,7 @@ schema("/gateways/:name") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_gateway),
                 summary => <<"Update the gateway confs">>,
                 parameters => params_gateway_name_in_path(),

apps/emqx_gateway/src/emqx_gateway_api_authn.erl

@@ -52,6 +52,8 @@
 %% internal export for emqx_gateway_api_listeners module
 -export([schema_authn/0]).
 
+-define(TAGS, [<<"Gateway Authentication">>]).
+
 %%--------------------------------------------------------------------
 %% minirest behaviour callbacks
 %%--------------------------------------------------------------------
@@ -182,7 +184,7 @@ schema("/gateways/:name/authentication") ->
         'operationId' => authn,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_authn),
                 summary => <<"Get Authenticator Configuration">>,
                 parameters => params_gateway_name_in_path(),
@@ -196,7 +198,7 @@ schema("/gateways/:name/authentication") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_authn),
                 summary => <<"Update Authenticator Configuration">>,
                 parameters => params_gateway_name_in_path(),
@@ -206,7 +208,7 @@ schema("/gateways/:name/authentication") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_authn),
                 summary => <<"Create an Authenticator for a Gateway">>,
                 parameters => params_gateway_name_in_path(),
@@ -216,7 +218,7 @@ schema("/gateways/:name/authentication") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_authn),
                 summary => <<"Delete the Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path(),
@@ -229,7 +231,7 @@ schema("/gateways/:name/authentication/users") ->
         'operationId' => users,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_users),
                 summary => <<"List users for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -247,7 +249,7 @@ schema("/gateways/:name/authentication/users") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_user),
                 summary => <<"Add User for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path(),
@@ -271,7 +273,7 @@ schema("/gateways/:name/authentication/users/:uid") ->
         'operationId' => users_insta,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_user),
                 summary => <<"Get User Info for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -288,7 +290,7 @@ schema("/gateways/:name/authentication/users/:uid") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_user),
                 summary => <<"Update User Info for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -309,7 +311,7 @@ schema("/gateways/:name/authentication/users/:uid") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_user),
                 summary => <<"Delete User for a Gateway Authenticator">>,
                 parameters => params_gateway_name_in_path() ++

apps/emqx_gateway/src/emqx_gateway_api_authn_user_import.erl

@@ -45,6 +45,8 @@
     import_listener_users/2
 ]).
 
+-define(TAGS, [<<"Gateway Authentication">>]).
+
 %%--------------------------------------------------------------------
 %% minirest behaviour callbacks
 %%--------------------------------------------------------------------
@@ -122,7 +124,7 @@ schema("/gateways/:name/authentication/import_users") ->
         'operationId' => import_users,
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(emqx_gateway_api_authn, import_users),
                 summary => <<"Import Users">>,
                 parameters => params_gateway_name_in_path(),
@@ -136,7 +138,7 @@ schema("/gateways/:name/listeners/:id/authentication/import_users") ->
         'operationId' => import_listener_users,
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(emqx_gateway_api_listeners, import_users),
                 summary => <<"Import Users">>,
                 parameters => params_gateway_name_in_path() ++

apps/emqx_gateway/src/emqx_gateway_api_clients.erl

@@ -59,6 +59,8 @@
     format_channel_info/1
 ]).
 
+-define(TAGS, [<<"Gateway Clients">>]).
+
 %%--------------------------------------------------------------------
 %% APIs
 %%--------------------------------------------------------------------
@@ -467,7 +469,7 @@ schema("/gateways/:name/clients") ->
         'operationId' => clients,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_clients),
                 summary => <<"List Gateway's Clients">>,
                 parameters => params_client_query(),
@@ -480,7 +482,7 @@ schema("/gateways/:name/clients/:clientid") ->
         'operationId' => clients_insta,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_client),
                 summary => <<"Get Client Info">>,
                 parameters => params_client_insta(),
@@ -489,7 +491,7 @@ schema("/gateways/:name/clients/:clientid") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(kick_client),
                 summary => <<"Kick out Client">>,
                 parameters => params_client_insta(),
@@ -502,7 +504,7 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
         'operationId' => subscriptions,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_subscriptions),
                 summary => <<"List Client's Subscription">>,
                 parameters => params_client_insta(),
@@ -518,7 +520,7 @@ schema("/gateways/:name/clients/:clientid/subscriptions") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_subscription),
                 summary => <<"Add Subscription for Client">>,
                 parameters => params_client_insta(),
@@ -542,7 +544,7 @@ schema("/gateways/:name/clients/:clientid/subscriptions/:topic") ->
         'operationId' => subscriptions,
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_subscription),
                 summary => <<"Delete Client's Subscription">>,
                 parameters => params_topic_name_in_path() ++ params_client_insta(),

apps/emqx_gateway/src/emqx_gateway_api_listeners.erl

@@ -60,6 +60,8 @@
 %% RPC
 -export([do_listeners_cluster_status/1]).
 
+-define(TAGS, [<<"Gateway Listeners">>]).
+
 %%--------------------------------------------------------------------
 %% minirest behaviour callbacks
 %%--------------------------------------------------------------------
@@ -358,7 +360,7 @@ schema("/gateways/:name/listeners") ->
         'operationId' => listeners,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_listeners),
                 summary => <<"List All Listeners">>,
                 parameters => params_gateway_name_in_path(),
@@ -374,7 +376,7 @@ schema("/gateways/:name/listeners") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_listener),
                 summary => <<"Add a Listener">>,
                 parameters => params_gateway_name_in_path(),
@@ -400,7 +402,7 @@ schema("/gateways/:name/listeners/:id") ->
         'operationId' => listeners_insta,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_listener),
                 summary => <<"Get the Listener Configs">>,
                 parameters => params_gateway_name_in_path() ++
@@ -417,7 +419,7 @@ schema("/gateways/:name/listeners/:id") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_listener),
                 summary => <<"Delete the Listener">>,
                 parameters => params_gateway_name_in_path() ++
@@ -427,7 +429,7 @@ schema("/gateways/:name/listeners/:id") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_listener),
                 summary => <<"Update the Listener Configs">>,
                 parameters => params_gateway_name_in_path() ++
@@ -452,7 +454,7 @@ schema("/gateways/:name/listeners/:id/authentication") ->
         'operationId' => listeners_insta_authn,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_listener_authn),
                 summary => <<"Get the Listener's Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -467,7 +469,7 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_listener_authn),
                 summary => <<"Create an Authenticator for a Listener">>,
                 parameters => params_gateway_name_in_path() ++
@@ -478,7 +480,7 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_listener_authn),
                 summary => <<"Update the Listener Authenticator configs">>,
                 parameters => params_gateway_name_in_path() ++
@@ -489,7 +491,7 @@ schema("/gateways/:name/listeners/:id/authentication") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_listener_authn),
                 summary => <<"Delete the Listener's Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -503,7 +505,7 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
         'operationId' => users,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(list_users),
                 summary => <<"List Authenticator's Users">>,
                 parameters => params_gateway_name_in_path() ++
@@ -521,7 +523,7 @@ schema("/gateways/:name/listeners/:id/authentication/users") ->
             },
         post =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(add_user),
                 summary => <<"Add User for an Authenticator">>,
                 parameters => params_gateway_name_in_path() ++
@@ -546,7 +548,7 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
         'operationId' => users_insta,
         get =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(get_user),
                 summary => <<"Get User Info">>,
                 parameters => params_gateway_name_in_path() ++
@@ -564,7 +566,7 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
             },
         put =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(update_user),
                 summary => <<"Update User Info">>,
                 parameters => params_gateway_name_in_path() ++
@@ -586,7 +588,7 @@ schema("/gateways/:name/listeners/:id/authentication/users/:uid") ->
             },
         delete =>
             #{
-                tags => [<<"Gateways">>],
+                tags => ?TAGS,
                 desc => ?DESC(delete_user),
                 summary => <<"Delete User">>,
                 parameters => params_gateway_name_in_path() ++

apps/emqx_gateway/src/lwm2m/emqx_lwm2m_api.erl

@@ -27,6 +27,7 @@
 
 -define(PATH(Suffix), "/gateways/lwm2m/clients/:clientid" Suffix).
 -define(DATA_TYPE, ['Integer', 'Float', 'Time', 'String', 'Boolean', 'Opaque', 'Objlnk']).
+-define(TAGS, [<<"LwM2M Gateways">>]).
 
 -import(hoconsc, [mk/2, ref/1, ref/2]).
 -import(emqx_dashboard_swagger, [error_codes/2]).
@@ -45,7 +46,7 @@ schema(?PATH("/lookup")) ->
     #{
         'operationId' => lookup,
         get => #{
-            tags => [<<"Gateways">>],
+            tags => ?TAGS,
             desc => ?DESC(lookup_resource),
             summary => <<"List Client's Resources">>,
             parameters => [
@@ -70,7 +71,7 @@ schema(?PATH("/observe")) ->
     #{
         'operationId' => observe,
         post => #{
-            tags => [<<"Gateways">>],
+            tags => ?TAGS,
             desc => ?DESC(observe_resource),
             summary => <<"Observe a Resource">>,
             parameters => [
@@ -89,7 +90,7 @@ schema(?PATH("/read")) ->
     #{
         'operationId' => read,
         post => #{
-            tags => [<<"Gateways">>],
+            tags => ?TAGS,
             desc => ?DESC(read_resource),
             summary => <<"Read Value from a Resource Path">>,
             parameters => [
@@ -106,8 +107,8 @@ schema(?PATH("/write")) ->
     #{
         'operationId' => write,
         post => #{
+            tags => ?TAGS,
             desc => ?DESC(write_resource),
-            tags => [<<"Gateways">>],
             summary => <<"Write a Value to Resource Path">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},