From 1a0862913e41b33d39728ceba5cd0b39f8b8d136 Mon Sep 17 00:00:00 2001 From: JimMoen Date: Fri, 21 Jan 2022 17:26:54 +0800 Subject: [PATCH 1/3] refactor(api): swagger api tag `mqtt` --- apps/emqx_modules/include/emqx_modules.hrl | 18 ++++++++++++++++++ apps/emqx_modules/src/emqx_delayed_api.erl | 11 ++++++----- apps/emqx_modules/src/emqx_rewrite_api.erl | 4 +++- .../src/emqx_topic_metrics_api.erl | 4 +--- 4 files changed, 28 insertions(+), 9 deletions(-) diff --git a/apps/emqx_modules/include/emqx_modules.hrl b/apps/emqx_modules/include/emqx_modules.hrl index 334173015..6bb95eea2 100644 --- a/apps/emqx_modules/include/emqx_modules.hrl +++ b/apps/emqx_modules/include/emqx_modules.hrl @@ -1,5 +1,23 @@ +%%-------------------------------------------------------------------- +%% 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">>]). diff --git a/apps/emqx_modules/src/emqx_delayed_api.erl b/apps/emqx_modules/src/emqx_delayed_api.erl index 56d782580..9a878f7f2 100644 --- a/apps/emqx_modules/src/emqx_delayed_api.erl +++ b/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 => #{ diff --git a/apps/emqx_modules/src/emqx_rewrite_api.erl b/apps/emqx_modules/src/emqx_rewrite_api.erl index 534864c74..6590b2cac 100644 --- a/apps/emqx_modules/src/emqx_rewrite_api.erl +++ b/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")), diff --git a/apps/emqx_modules/src/emqx_topic_metrics_api.erl b/apps/emqx_modules/src/emqx_topic_metrics_api.erl index 76419d4af..9fe583ca3 100644 --- a/apps/emqx_modules/src/emqx_topic_metrics_api.erl +++ b/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}). From ab94b497627005057beaa3000c6dbd4f4cc42011 Mon Sep 17 00:00:00 2001 From: JimMoen Date: Fri, 21 Jan 2022 17:33:31 +0800 Subject: [PATCH 2/3] refactor(api): event_message swagger spec --- apps/emqx_modules/include/emqx_modules.hrl | 1 + .../src/emqx_event_message_api.erl | 50 ++++++++++--------- apps/emqx_modules/src/emqx_modules_schema.erl | 28 ++++++++--- 3 files changed, 49 insertions(+), 30 deletions(-) diff --git a/apps/emqx_modules/include/emqx_modules.hrl b/apps/emqx_modules/include/emqx_modules.hrl index 6bb95eea2..8d505969c 100644 --- a/apps/emqx_modules/include/emqx_modules.hrl +++ b/apps/emqx_modules/include/emqx_modules.hrl @@ -21,3 +21,4 @@ -define(REPORT_INTERVAR, 604800). -define(API_TAG_MQTT, [<<"mqtt">>]). +-define(API_SCHEMA_MODULE, emqx_modules_schema). diff --git a/apps/emqx_modules/src/emqx_event_message_api.erl b/apps/emqx_modules/src/emqx_event_message_api.erl index 55e12f591..65c33c0d7 100644 --- a/apps/emqx_modules/src/emqx_event_message_api.erl +++ b/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() -> - emqx_mgmt_api_configs:gen_schema(emqx:get_config([event_message])). +paths() -> + ["/mqtt/event_message"]. -event_message_api() -> - Path = "/mqtt/event_message", - Metadata = #{ - get => #{ - description => <<"Event Message">>, - responses => #{ - <<"200">> => schema(conf_schema()) +schema("/mqtt/event_message") -> + #{ 'operationId' => event_message + , get => + #{ description => <<"Event Message">> + , tags => ?API_TAG_MQTT + , responses => + #{200 => status_schema(<<"Get Event Message config successfully">>)} } - }, - put => #{ - description => <<"Update Event Message">>, - 'requestBody' => schema(conf_schema()), - responses => #{ - <<"200">> => schema(conf_schema()) + , put => + #{ description => <<"Update Event Message">> + , tags => ?API_TAG_MQTT + , 'requestBody' => status_schema(<<"Update Event Message config">>) + , responses => + #{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()}; diff --git a/apps/emqx_modules/src/emqx_modules_schema.erl b/apps/emqx_modules/src/emqx_modules_schema.erl index 0c5363e16..99e0b4860 100644 --- a/apps/emqx_modules/src/emqx_modules_schema.erl +++ b/apps/emqx_modules/src/emqx_modules_schema.erl @@ -51,13 +51,27 @@ fields("rewrite") -> fields("event_message") -> - [ {"$event/client_connected", sc(boolean(), #{default => false})} - , {"$event/client_disconnected", sc(boolean(), #{default => false})} - , {"$event/client_subscribed", sc(boolean(), #{default => false})} - , {"$event/client_unsubscribed", sc(boolean(), #{default => false})} - , {"$event/message_delivered", sc(boolean(), #{default => false})} - , {"$event/message_acked", sc(boolean(), #{default => false})} - , {"$event/message_dropped", sc(boolean(), #{default => false})} + [ { '$event/client_connected' + , sc( boolean() + , #{desc => <<"Client connected to EMQ X event">>, default => false})} + , { '$event/client_disconnected' + , sc(boolean() + , #{desc => <<"Client disconnected to EMQ X event">>, 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") -> From f30c16e47c9de0400d6f6dc84fc5cfd109ed4b83 Mon Sep 17 00:00:00 2001 From: JimMoen Date: Fri, 21 Jan 2022 17:47:24 +0800 Subject: [PATCH 3/3] refactor(schema): description use binary --- apps/emqx_modules/src/emqx_modules_schema.erl | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/apps/emqx_modules/src/emqx_modules_schema.erl b/apps/emqx_modules/src/emqx_modules_schema.erl index 99e0b4860..a7c6c2952 100644 --- a/apps/emqx_modules/src/emqx_modules_schema.erl +++ b/apps/emqx_modules/src/emqx_modules_schema.erl @@ -43,10 +43,16 @@ fields("delayed") -> ]; fields("rewrite") -> - [ {action, sc(hoconsc:enum([subscribe, publish, all]), #{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 } + [ { action + , sc( hoconsc:enum([subscribe, publish, all]) + , #{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 } ];