From 2939803215878c5655727e620135467e3ad72b78 Mon Sep 17 00:00:00 2001
From: JimMoen <LnJimMoen@outlook.com>
Date: Thu, 13 Jan 2022 15:52:53 +0800
Subject: [PATCH] refactor(api): telemetry api swagger spec

---
 apps/emqx_modules/src/emqx_telemetry_api.erl | 178 ++++++++++++++-----
 1 file changed, 130 insertions(+), 48 deletions(-)

diff --git a/apps/emqx_modules/src/emqx_telemetry_api.erl b/apps/emqx_modules/src/emqx_telemetry_api.erl
index 887de4305..befe41d06 100644
--- a/apps/emqx_modules/src/emqx_telemetry_api.erl
+++ b/apps/emqx_modules/src/emqx_telemetry_api.erl
@@ -18,12 +18,9 @@
 
 -behaviour(minirest_api).
 
--import(emqx_mgmt_util, [ schema/1
-                        , object_schema/1
-                        , object_schema/2
-                        , properties/1
-                        , bad_request/0
-                        ]).
+-include_lib("typerefl/include/types.hrl").
+
+-import(hoconsc, [mk/2, ref/1, ref/2, array/1]).
 
 % -export([cli/1]).
 
@@ -33,54 +30,139 @@
 
 -export([enable_telemetry/2]).
 
--export([api_spec/0]).
+-export([ api_spec/0
+        , paths/0
+        , schema/1
+        , fields/1
+        ]).
+
+-define(BAD_REQUEST, 'BAD_REQUEST').
 
 api_spec() ->
-    {[status_api(), data_api()], []}.
+    emqx_dashboard_swagger:spec(?MODULE, #{check_schema => true}).
 
-properties() ->
-    properties([
-        {emqx_version, string, <<"EMQ X Version">>},
-        {license, object, [{edition, string, <<"EMQ X License">>}]},
-        {os_name, string, <<"OS Name">>},
-        {os_version, string, <<"OS Version">>},
-        {otp_version, string, <<"Erlang/OTP Version">>},
-        {up_time, string, <<"EMQ X Runtime">>},
-        {uuid, string, <<"EMQ X UUID">>},
-        {nodes_uuid, string, <<"EMQ X Cluster Nodes UUID">>},
-        {active_plugins, {array, string}, <<"EMQ X Active Plugins">>},
-        {active_modules, {array, string}, <<"EMQ X Active Modules">>},
-        {num_clients, integer, <<"EMQ X Current Connections">>},
-        {messages_received, integer, <<"EMQ X Current Received Message">>},
-        {messages_sent, integer, <<"EMQ X Current Sent Message">>}
-    ]).
+paths() ->
+    [ "/telemetry/status"
+    , "/telemetry/data"
+    ].
 
-status_api() ->
-    Props = properties([{enable, boolean}]),
-    Metadata = #{
-        get => #{
-            description => "Get telemetry status",
-            responses => #{<<"200">> => object_schema(Props)}
-        },
-        put => #{
-            description => "Enable or disable telemetry",
-            'requestBody' => object_schema(Props),
-            responses => #{
-                <<"200">> =>
-                    object_schema(properties([{enable, boolean, <<"">>}]),
-                        <<"Enable or disable telemetry successfully">>),
-                <<"400">> => bad_request()
+schema("/telemetry/status") ->
+    #{ 'operationId' => status,
+       get =>
+           #{ description => <<"Get telemetry status">>
+            , responses =>
+                  #{ 200 => status_schema(<<"Get telemetry status">>)}
+            },
+       put =>
+           #{ description => <<"Enable or disable telemetry">>
+            , 'requestBody' => status_schema(<<"Enable or disable telemetry">>)
+            , responses =>
+                  #{ 200 => status_schema(<<"Enable or disable telemetry successfully">>)
+                   , 400 => emqx_dashboard_swagger:error_codes([?BAD_REQUEST], <<"Bad Request">>)
+                   }
             }
-        }
-    },
-    {"/telemetry/status", Metadata, status}.
+     };
+schema("/telemetry/data") ->
+    #{ 'operationId' => data,
+       get =>
+           #{ description => <<"Get telemetry data">>
+            , responses =>
+                  #{ 200 => mk(ref(?MODULE, telemetry), #{ desc => <<"Get telemetry data">>})}}
+     }.
 
-data_api() ->
-    Metadata = #{
-        get => #{
-            responses => #{
-                <<"200">> => object_schema(properties(), <<"Get telemetry data">>)}}},
-    {"/telemetry/data", Metadata, data}.
+status_schema(Desc) ->
+    mk(ref(?MODULE, status), #{desc => Desc}).
+
+fields(status) ->
+    [ { enable
+      , mk( boolean()
+          , #{ desc => <<"Telemetry status">>
+             , default => false
+             , example => false
+             })
+      }
+    ];
+fields(telemetry) ->
+    [ { emqx_version
+      , mk( string()
+          , #{ desc => <<"EMQ X Version">>
+             , example => <<"5.0.0-beta.3-32d1547c">>
+             })
+      }
+    , { license
+      , mk( map()
+          , #{ desc => <<"EMQ X License">>
+             , example => #{edition => <<"community">>}
+             })
+      }
+    , { os_name
+      , mk( string()
+          , #{ desc => <<"OS Name">>
+             , example => <<"Linux">>
+             })
+      }
+    , { os_version
+      , mk( string()
+          , #{ desc => <<"OS Version">>
+             , example => <<"20.04">>
+             })
+      }
+    , { otp_version
+      , mk( string()
+          , #{ desc => <<"Erlang/OTP Version">>
+             , example => <<"24">>
+             })
+      }
+    , { up_time
+      , mk( integer()
+          , #{ desc => <<"EMQ X Runtime">>
+             , example => 20220113
+             })
+      }
+    , { uuid
+      , mk( string()
+          , #{ desc => <<"EMQ X UUID">>
+             , example => <<"AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF">>
+             })
+      }
+    , { nodes_uuid
+      , mk( array(binary())
+          , #{ desc => <<"EMQ X Cluster Nodes UUID">>
+             , example => [ <<"AAAAAAAA-BBBB-CCCC-2022-DDDDEEEEFFF">>
+                          , <<"ZZZZZZZZ-CCCC-BBBB-2022-DDDDEEEEFFF">>]
+             })
+      }
+    , { active_plugins
+      , mk( array(binary())
+          , #{ desc => <<"EMQ X Active Plugins">>
+             , example => [<<"Plugin A">>, <<"Plugin B">>]
+             })
+      }
+    , { active_modules
+      , mk( array(binary())
+          , #{ desc => <<"EMQ X Active Modules">>
+             , example => [<<"Module A">>, <<"Module B">>]
+             })
+      }
+    , { num_clients
+      , mk( integer()
+          , #{ desc => <<"EMQ X Current Connections">>
+             , example => 20220113
+             })
+      }
+    , { messages_received
+      , mk( integer()
+          , #{ desc => <<"EMQ X Current Received Message">>
+             , example => 2022
+             })
+      }
+    , { messages_sent
+      , mk( integer()
+          , #{ desc => <<"EMQ X Current Sent Message">>
+             , example => 2022
+             })
+      }
+    ].
 
 %%--------------------------------------------------------------------
 %% HTTP API