refactor(retainer): refactor the api use swagger

apps/emqx_retainer/src/emqx_retainer_api.erl

@@ -19,105 +19,102 @@
 -behaviour(minirest_api).
 
 -include_lib("emqx/include/emqx.hrl").
+-include_lib("typerefl/include/types.hrl").
 
--export([api_spec/0]).
+%% API
+-export([api_spec/0, paths/0, schema/1, namespace/0, fields/1]).
 
 -export([ lookup_retained_warp/2
         , with_topic_warp/2
         , config/2]).
 
--import(emqx_mgmt_api_configs, [gen_schema/1]).
+-import(hoconsc, [mk/2, ref/1, ref/2, array/1]).
--import(emqx_mgmt_util, [ object_array_schema/2
+-import(emqx_dashboard_swagger, [error_codes/2]).
-                        , object_schema/2
-                        , schema/1
-                        , schema/2
-                        , error_schema/2
-                        , page_params/0
-                        , properties/1]).
 
 -define(MAX_PAYLOAD_SIZE, 1048576). %% 1MB = 1024 x 1024
+-define(PREFIX, "/mqtt/retainer").
+-define(TAGS, [<<"retainer">>]).
+
+namespace() -> "retainer".
 
 api_spec() ->
-    {[lookup_retained_api(), with_topic_api(), config_api()], []}.
+    emqx_dashboard_swagger:spec(?MODULE, #{check_schema => true, translate_body => true}).
 
-conf_schema() ->
+paths() ->
-    gen_schema(emqx:get_raw_config([retainer])).
+    [?PREFIX, ?PREFIX ++ "/messages", ?PREFIX ++ "/message/:topic"].
 
-message_props() ->
+schema(?PREFIX) ->
-    properties([
+    #{operationId => config,
-        {id, string, <<"Message ID">>},
+      get => #{tags => ?TAGS,
-        {topic, string, <<"MQTT Topic">>},
+               description => <<"Get retainer config">>,
-        {qos, integer, <<"MQTT QoS">>, [0, 1, 2]},
+               responses => #{200 => mk(conf_schema(), #{desc => "The config content"}),
-        {payload, string, <<"MQTT Payload">>},
+                              404 => error_codes(['NOT_FOUND'], <<"Config not found">>)
-        {publish_at, string, <<"Publish datetime, in RFC 3339 format">>},
+                             }
-        {from_clientid, string, <<"Publisher ClientId">>},
+              },
-        {from_username, string, <<"Publisher Username">>}
+      put => #{tags => ?TAGS,
-    ]).
+               description => <<"Update retainer config">>,
+               'requestBody' => mk(conf_schema(), #{desc => "The config content"}),
+               responses => #{200 => mk(conf_schema(), #{desc => "Update configs successfully"}),
+                              404 => error_codes(['UPDATE_FAILED'], <<"Update config failed">>)
+                             }
+              }
+     };
 
-parameters() ->
+schema(?PREFIX ++ "/messages") ->
-    [#{
+    #{operationId => lookup_retained_warp,
-        name => topic,
+      get => #{tags => ?TAGS,
-        in => path,
-        required => true,
-        schema => #{type => "string"}
-    }].
-
-lookup_retained_api() ->
-    Metadata = #{
-        get => #{
                description => <<"List retained messages">>,
                parameters => page_params(),
-            responses => #{
+               responses => #{200 => mk(array(ref(message_summary)), #{desc => "The result list"}),
-                <<"200">> => object_array_schema(
+                              405 => error_codes(['ACTION_NOT_ALLOWED'], <<"Unsupported backend">>)
-                    maps:without([payload], message_props()),
-                    <<"List retained messages">>),
-                <<"405">> => schema(<<"NotAllowed">>)
                              }
               }
-    },
+        };
-    {"/mqtt/retainer/messages", Metadata, lookup_retained_warp}.
 
-with_topic_api() ->
+schema(?PREFIX ++ "/message/:topic") ->
-    MetaData = #{
+    #{operationId => with_topic_warp,
-        get => #{
+      get => #{tags => ?TAGS,
-            description => <<"lookup matching messages">>,
+               description => <<"Lookup a message by a topic without wildcards">>,
                parameters => parameters(),
-            responses => #{
+               responses => #{200 => mk(ref(message), #{desc => "Details of the message"}),
-                <<"200">> => object_schema(message_props(), <<"List retained messages">>),
+                              404 => error_codes(['NOT_FOUND'], <<"Viewed message doesn't exist">>),
-                <<"404">> => error_schema(<<"Retained Not Exists">>, ['NOT_FOUND']),
+                              405 => error_codes(['ACTION_NOT_ALLOWED'], <<"Unsupported backend">>)
-                <<"405">> => schema(<<"NotAllowed">>)
                              }
               },
-        delete => #{
+      delete => #{tags => ?TAGS,
-            description => <<"delete matching messages">>,
+                  description => <<"Delete matching messages">>,
                   parameters => parameters(),
-            responses => #{
+                  responses => #{204 => <<>>,
-                <<"204">> => schema(<<"Succeeded">>),
+                                 405 => error_codes(['ACTION_NOT_ALLOWED'],
-                <<"405">> => schema(<<"NotAllowed">>)
+                                                    <<"Unsupported backend">>)
                                 }
                  }
-    },
+     }.
-    {"/mqtt/retainer/message/:topic", MetaData, with_topic_warp}.
 
-config_api() ->
+page_params() ->
-    MetaData = #{
+    emqx_dashboard_swagger:fields(page) ++ emqx_dashboard_swagger:fields(limit).
-        get => #{
+
-            description => <<"get retainer config">>,
+conf_schema() ->
-            responses => #{
+    ref(emqx_retainer_schema, "retainer").
-                <<"200">> => schema(conf_schema(), <<"Get configs successfully">>),
+
-                <<"404">> => error_schema(<<"Config not found">>, ['NOT_FOUND'])
+parameters() ->
-            }
+    [{topic, mk(binary(), #{in => path,
-        },
+                            required => true,
-        put => #{
+                            desc => "The target topic"
-            description => <<"Update retainer config">>,
+                           })}].
-            'requestBody' => schema(conf_schema()),
+
-            responses => #{
+fields(message_summary) ->
-                <<"200">> => schema(conf_schema(), <<"Update configs successfully">>),
+    [ {id, mk(binary(), #{desc => <<"Message ID">>})}
-                <<"400">> => error_schema(<<"Update configs failed">>, ['UPDATE_FAILED'])
+    , {topic, mk(binary(), #{desc => "The topic"})}
-            }
+    , {qos, mk(emqx_schema:qos(), #{desc => "The QoS"})}
-        }
+    , {publish_at, mk(string(), #{desc => "Publish datetime, in RFC 3339 format"})}
-    },
+    , {from_clientid, mk(binary(), #{desc => "Publisher ClientId"})}
-    {"/mqtt/retainer", MetaData, config}.
+    , {from_username, mk(binary(), #{desc => "Publisher Username"})}
+    ];
+
+fields(message) ->
+    [{payload, mk(binary(), #{desc => "The payload content"})} |
+     fields(message_summary)].
 
 lookup_retained_warp(Type, Params) ->
     check_backend(Type, Params, fun lookup_retained/2).
@@ -134,7 +131,7 @@ config(put, #{body := Body}) ->
         {200, emqx:get_raw_config([retainer])}
     catch _:Reason:_ ->
             {400,
-             #{code => 'UPDATE_FAILED',
+             #{code => <<"UPDATE_FAILED">>,
                message => iolist_to_binary(io_lib:format("~p~n", [Reason]))}}
     end.
 
@@ -154,7 +151,9 @@ with_topic(get, #{bindings := Bindings}) ->
         [H | _] ->
             {200, format_detail_message(H)};
         _ ->
-            {404, #{code => 'NOT_FOUND'}}
+            {404, #{code => <<"NOT_FOUND">>,
+                    message => <<"Viewed message doesn't exist">>
+                   }}
     end;
 
 with_topic(delete, #{bindings := Bindings}) ->
@@ -193,6 +192,7 @@ check_backend(Type, Params, Cont) ->
             Cont(Type, Params);
         _ ->
             {405,
-             #{<<"content-type">> => <<"text/plain">>},
+             #{code => <<"ACTION_NOT_ALLOWED">>,
-             <<"This API only for built in database">>}
+               message => <<"This API only for built in database">>}
+            }
     end.