Merge pull request #6826 from JimMoen/refactor-event-message-api

refactor(api): event_message swagger spec

apps/emqx_modules/include/emqx_modules.hrl

@@ -1,5 +1,24 @@
+%%--------------------------------------------------------------------
+%% Copyright (c) 2021-2022 EMQ Technologies Co., Ltd. All Rights Reserved.
+%%
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%--------------------------------------------------------------------
+
 %% The destination URL for the telemetry data report
 -define(TELEMETRY_URL, "https://telemetry.emqx.io/api/telemetry").
 
 %% Interval for reporting telemetry data, Default: 7d
 -define(REPORT_INTERVAR, 604800).
+
+-define(API_TAG_MQTT, [<<"mqtt">>]).
+-define(API_SCHEMA_MODULE, emqx_modules_schema).

apps/emqx_modules/src/emqx_delayed_api.erl

@@ -19,6 +19,7 @@
 -behaviour(minirest_api).
 
 -include_lib("typerefl/include/types.hrl").
+-include("emqx_modules.hrl").
 
 -import(hoconsc, [mk/2, ref/1, ref/2]).
 
@@ -62,7 +63,7 @@ schema("/mqtt/delayed") ->
     #{
         'operationId' => status,
         get => #{
-            tags => [<<"mqtt">>],
+            tags => ?API_TAG_MQTT,
             description => <<"Get delayed status">>,
             summary => <<"Get delayed status">>,
             responses => #{
@@ -70,7 +71,7 @@ schema("/mqtt/delayed") ->
             }
         },
         put => #{
-            tags => [<<"mqtt">>],
+            tags => ?API_TAG_MQTT,
             description => <<"Enable or disable delayed, set max delayed messages">>,
             'requestBody' => ref(emqx_modules_schema, "delayed"),
             responses => #{
@@ -85,7 +86,7 @@ schema("/mqtt/delayed") ->
 schema("/mqtt/delayed/messages/:msgid") ->
     #{'operationId' => delayed_message,
         get => #{
-            tags => [<<"mqtt">>],
+            tags => ?API_TAG_MQTT,
             description => <<"Get delayed message">>,
             parameters => [{msgid, mk(binary(), #{in => path, desc => <<"delay message ID">>})}],
             responses => #{
@@ -97,7 +98,7 @@ schema("/mqtt/delayed/messages/:msgid") ->
             }
         },
         delete => #{
-            tags => [<<"mqtt">>],
+            tags => ?API_TAG_MQTT,
             description => <<"Delete delayed message">>,
             parameters => [{msgid, mk(binary(), #{in => path, desc => <<"delay message ID">>})}],
             responses => #{
@@ -113,7 +114,7 @@ schema("/mqtt/delayed/messages") ->
     #{
         'operationId' => delayed_messages,
         get => #{
-            tags => [<<"mqtt">>],
+            tags => ?API_TAG_MQTT,
             description => <<"List delayed messages">>,
             parameters => [ref(emqx_dashboard_swagger, page), ref(emqx_dashboard_swagger, limit)],
             responses => #{

apps/emqx_modules/src/emqx_event_message_api.erl

@@ -17,37 +17,41 @@
 
 -behaviour(minirest_api).
 
--export([api_spec/0]).
+-import(hoconsc, [mk/2, ref/2]).
+-include("emqx_modules.hrl").
+
+-export([ api_spec/0
+        , paths/0
+        , schema/1
+        ]).
 
 -export([event_message/2]).
 
--import(emqx_mgmt_util, [ schema/1
-                        ]).
-
 api_spec() ->
-    {[event_message_api()], []}.
+    emqx_dashboard_swagger:spec(?MODULE, #{check_schema => true}).
 
-conf_schema() ->
+paths() ->
-    emqx_mgmt_api_configs:gen_schema(emqx:get_config([event_message])).
+    ["/mqtt/event_message"].
 
-event_message_api() ->
+schema("/mqtt/event_message") ->
-    Path = "/mqtt/event_message",
+    #{ 'operationId' => event_message
-    Metadata = #{
+     , get =>
-        get => #{
+           #{ description => <<"Event Message">>
-            description => <<"Event Message">>,
+            , tags => ?API_TAG_MQTT
-            responses => #{
+            , responses =>
-                <<"200">> => schema(conf_schema())
+                  #{200 => status_schema(<<"Get Event Message config successfully">>)}
             }
-        },
+     , put =>
-        put => #{
+           #{ description => <<"Update Event Message">>
-            description => <<"Update Event Message">>,
+            , tags => ?API_TAG_MQTT
-            'requestBody' => schema(conf_schema()),
+            , 'requestBody' => status_schema(<<"Update Event Message config">>)
-            responses => #{
+            , responses =>
-                <<"200">> => schema(conf_schema())
+                  #{200 => status_schema(<<"Update Event Message config successfully">>)}
             }
-        }
+     }.
-    },
+
-    {Path, Metadata, event_message}.
+status_schema(Desc) ->
+    mk(ref(?API_SCHEMA_MODULE, "event_message"), #{in => body, desc => Desc}).
 
 event_message(get, _Params) ->
     {200, emqx_event_message:list()};

apps/emqx_modules/src/emqx_modules_schema.erl

@@ -43,21 +43,41 @@ fields("delayed") ->
     ];
 
 fields("rewrite") ->
-    [ {action, sc(hoconsc:enum([subscribe, publish, all]), #{desc => "Action", example => publish})}
+    [ { action
-    , {source_topic, sc(binary(), #{desc => "Origin Topic", example => "x/#"})}
+      , sc( hoconsc:enum([subscribe, publish, all])
-    , {dest_topic, sc(binary(), #{desc => "Destination Topic", example => "z/y/$1"})}
+          , #{desc => <<"Action">>, example => publish})}
+    , { source_topic
+      , sc( binary()
+          , #{desc => <<"Origin Topic">>, example => "x/#"})}
+    , { dest_topic
+      , sc( binary()
+          , #{desc => <<"Destination Topic">>, example => "z/y/$1"})}
     , { re, fun regular_expression/1 }
     ];
 
 
 fields("event_message") ->
-    [ {"$event/client_connected", sc(boolean(), #{default => false})}
+    [ { '$event/client_connected'
-    , {"$event/client_disconnected", sc(boolean(), #{default => false})}
+      , sc( boolean()
-    , {"$event/client_subscribed", sc(boolean(), #{default => false})}
+          , #{desc => <<"Client connected to EMQ X event">>, default => false})}
-    , {"$event/client_unsubscribed", sc(boolean(), #{default => false})}
+    , { '$event/client_disconnected'
-    , {"$event/message_delivered", sc(boolean(), #{default => false})}
+      , sc(boolean()
-    , {"$event/message_acked", sc(boolean(), #{default => false})}
+          , #{desc => <<"Client disconnected to EMQ X event">>, default => false})}
-    , {"$event/message_dropped", sc(boolean(), #{default => false})}
+    , { '$event/client_subscribed'
+      , sc( boolean()
+          , #{desc => <<"Client subscribe topic event">>, default => false})}
+    , { '$event/client_unsubscribed'
+      , sc( boolean()
+          , #{desc => <<"Client unsubscribe topic event">>, default => false})}
+    , { '$event/message_delivered'
+      , sc( boolean()
+          , #{desc => <<"Message delivered event">>, default => false})}
+    , { '$event/message_acked'
+      , sc( boolean()
+          , #{desc => <<"Message acked event">>, default => false})}
+    , { '$event/message_dropped'
+      , sc( boolean()
+          , #{desc => <<"Message dropped event">>, default => false})}
     ];
 
 fields("topic_metrics") ->

apps/emqx_modules/src/emqx_rewrite_api.erl

@@ -17,6 +17,7 @@
 
 -behaviour(minirest_api).
 -include_lib("typerefl/include/types.hrl").
+-include("emqx_modules.hrl").
 
 -export([api_spec/0, paths/0, schema/1]).
 
@@ -42,7 +43,7 @@ schema("/mqtt/topic_rewrite") ->
     #{
         operationId => topic_rewrite,
         get => #{
-            tags => [mqtt],
+            tags => ?API_TAG_MQTT,
             description => <<"List rewrite topic.">>,
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")),
@@ -51,6 +52,7 @@ schema("/mqtt/topic_rewrite") ->
         },
         put => #{
             description => <<"Update rewrite topic">>,
+            tags => ?API_TAG_MQTT,
             requestBody => hoconsc:mk(hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")),#{}),
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")),

apps/emqx_modules/src/emqx_topic_metrics_api.erl

@@ -19,6 +19,7 @@
 -behaviour(minirest_api).
 
 -include_lib("typerefl/include/types.hrl").
+-include("emqx_modules.hrl").
 
 -import( hoconsc
        , [ mk/2
@@ -46,9 +47,6 @@
 -define(BAD_RPC, 'BAD_RPC').
 -define(BAD_REQUEST, 'BAD_REQUEST').
 
--define(API_TAG_MQTT, [<<"mqtt">>]).
-
-
 api_spec() ->
     emqx_dashboard_swagger:spec(?MODULE, #{check_schema => true}).