feat(connector): add examples to the swagger doc

apps/emqx_connector/src/emqx_connector_api.erl

@@ -38,7 +38,7 @@
     catch
         error:{invalid_bridge_id, Id0} ->
             {400, #{code => 'INVALID_ID', message => <<"invalid_bridge_id: ", Id0/binary,
-                ". Bridge ID must be of format 'bridge_type:name'">>}}
+                ". Bridge Ids must be of format {type}:{name}">>}}
     end).
 
 namespace() -> "connector".
@@ -53,18 +53,61 @@ error_schema(Code, Message) ->
     , {message, mk(string(), #{example => Message})}
     ].
 
+put_request_body_schema() ->
+    emqx_dashboard_swagger:schema_with_examples(
+        connector_info(put_req), connector_info_examples()).
+
+post_request_body_schema() ->
+    emqx_dashboard_swagger:schema_with_examples(
+        connector_info(post_req), connector_info_examples()).
+
+get_response_body_schema() ->
+    emqx_dashboard_swagger:schema_with_example(
+        connector_info(), connector_info_examples()).
+
 connector_info() ->
+    connector_info(resp).
+
+connector_info(resp) ->
     hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_info")
-                  ]).
+                  ]);
-
+connector_info(put_req) ->
-connector_test_info() ->
+    hoconsc:union([ ref(emqx_connector_mqtt_schema, "connector")
-    hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector_test_info")
+                  ]);
-                  ]).
+connector_info(post_req) ->
-
-connector_req() ->
     hoconsc:union([ ref(emqx_connector_schema, "mqtt_connector")
                   ]).
 
+connector_info_array_example() ->
+    [Config || #{value := Config} <- maps:values(connector_info_examples())].
+
+connector_info_examples() ->
+    #{
+        mqtt => #{
+            summary => <<"MQTT Bridge">>,
+            value => mqtt_info_example()
+        }
+    }.
+
+mqtt_info_example() ->
+    #{
+        type => <<"mqtt">>,
+        server => <<"127.0.0.1:1883">>,
+        reconnect_interval => <<"30s">>,
+        proto_ver => <<"v4">>,
+        bridge_mode => true,
+        username => <<"foo">>,
+        password => <<"bar">>,
+        clientid => <<"foo">>,
+        clean_start => true,
+        keepalive => <<"300s">>,
+        retry_interval => <<"30s">>,
+        max_inflight => 100,
+        ssl => #{
+            enable => false
+        }
+    }.
+
 param_path_id() ->
     [{id, mk(binary(), #{in => path, example => <<"mqtt:my_mqtt_connector">>})}].
 
@@ -74,9 +117,9 @@ schema("/connectors_test") ->
         post => #{
             tags => [<<"connectors">>],
             description => <<"Test creating a new connector by given Id <br>"
-                             "The ID must be of format 'type:name'">>,
+                             "The ID must be of format '{type}:{name}'">>,
             summary => <<"Test creating connector">>,
-            requestBody => connector_test_info(),
+            requestBody => post_request_body_schema(),
             responses => #{
                 200 => <<"Test connector OK">>,
                 400 => error_schema('TEST_FAILED', "connector test failed")
@@ -92,17 +135,19 @@ schema("/connectors") ->
             description => <<"List all connectors">>,
             summary => <<"List connectors">>,
             responses => #{
-                200 => mk(array(connector_info()), #{desc => "List of connectors"})
+                200 => emqx_dashboard_swagger:schema_with_example(
+                            array(connector_info()),
+                            connector_info_array_example())
             }
         },
         post => #{
             tags => [<<"connectors">>],
             description => <<"Create a new connector by given Id <br>"
-                             "The ID must be of format 'type:name'">>,
+                             "The ID must be of format '{type}:{name}'">>,
             summary => <<"Create connector">>,
-            requestBody => connector_info(),
+            requestBody => post_request_body_schema(),
             responses => #{
-                201 => connector_info(),
+                201 => get_response_body_schema(),
                 400 => error_schema('ALREADY_EXISTS', "connector already exists")
             }
         }
@@ -117,7 +162,7 @@ schema("/connectors/:id") ->
             summary => <<"Get connector">>,
             parameters => param_path_id(),
             responses => #{
-                200 => connector_info(),
+                200 => get_response_body_schema(),
                 404 => error_schema('NOT_FOUND', "Connector not found")
             }
         },
@@ -126,9 +171,9 @@ schema("/connectors/:id") ->
             description => <<"Update an existing connector by Id">>,
             summary => <<"Update connector">>,
             parameters => param_path_id(),
-            requestBody => connector_req(),
+            requestBody => put_request_body_schema(),
             responses => #{
-                200 => <<"Update connector successfully">>,
+                200 => get_response_body_schema(),
                 400 => error_schema('UPDATE_FAIL', "Update failed"),
                 404 => error_schema('NOT_FOUND', "Connector not found")
             }},
@@ -143,8 +188,8 @@ schema("/connectors/:id") ->
             }}
     }.
 
-'/connectors_test'(post, #{body := #{<<"bridge_type">> := ConnType} = Params}) ->
+'/connectors_test'(post, #{body := #{<<"type">> := ConnType} = Params}) ->
-    case emqx_connector:create_dry_run(ConnType, maps:remove(<<"bridge_type">>, Params)) of
+    case emqx_connector:create_dry_run(ConnType, maps:remove(<<"type">>, Params)) of
         ok -> {200};
         {error, Error} ->
             {400, error_msg('BAD_ARG', Error)}

apps/emqx_connector/src/emqx_connector_mqtt.erl

@@ -100,7 +100,7 @@ on_start(InstId, Conf) ->
     BasicConf = basic_config(Conf),
     BridgeConf = BasicConf#{
         name => InstanceId,
-        clientid => clientid(InstanceId),
+        clientid => clientid(maps:get(clientid, Conf, InstanceId)),
         subscriptions => make_sub_confs(maps:get(ingress, Conf, undefined)),
         forwards => make_forward_confs(maps:get(egress, Conf, undefined))
     },
@@ -190,4 +190,4 @@ basic_config(#{
     }.
 
 clientid(Id) ->
-    list_to_binary(lists:concat([Id, ":", node()])).
+    unicode:characters_to_binary([Id, ":", atom_to_list(node())], utf8).

apps/emqx_connector/src/emqx_connector_schema.erl

@@ -22,14 +22,13 @@ fields("connectors") ->
     ];
 
 fields("mqtt_connector") ->
-    emqx_connector_mqtt_schema:fields("connector");
+    [ {type, sc(mqtt, #{desc => "The Connector Type"})}
+    %, {name, sc(binary(), #{desc => "The Connector Name"})}
+    ]
+    ++ emqx_connector_mqtt_schema:fields("connector");
 
 fields("mqtt_connector_info") ->
-    [{id, sc(binary(), #{desc => "The connector Id"})}]
+    [{id, sc(binary(), #{desc => "The connector Id", example => "mqtt:foo"})}]
-    ++ fields("mqtt_connector");
-
-fields("mqtt_connector_test_info") ->
-    [{bridge_type, sc(mqtt, #{desc => "The Bridge Type"})}]
     ++ fields("mqtt_connector").
 
 sc(Type, Meta) -> hoconsc:mk(Type, Meta).

apps/emqx_connector/src/mqtt/emqx_connector_mqtt_schema.erl

@@ -66,8 +66,7 @@ fields("connector") ->
             })}
     , {clientid,
         sc(binary(),
-           #{ default => "emqx_${nodename}"
+           #{ desc => "The clientid of the MQTT protocol"
-            , desc => "The clientid of the MQTT protocol"
             })}
     , {clean_start,
         sc(boolean(),

apps/emqx_rule_engine/src/emqx_rule_engine_api.erl

@@ -92,7 +92,7 @@ api_rules_crud() ->
                 <<"200">> =>
                     emqx_mgmt_util:schema(resp_schema(), <<"Get rule successfully">>)}},
         put => #{
-            description => <<"Create or update a rule by given Id to all nodes in the cluster">>,
+            description => <<"Update a rule by given Id to all nodes in the cluster">>,
             parameters => [param_path_id()],
             'requestBody' => emqx_mgmt_util:schema(put_req_schema(), <<"Rule parameters">>),
             responses => #{
@@ -100,7 +100,7 @@ api_rules_crud() ->
                     emqx_mgmt_util:error_schema(<<"Invalid Parameters">>, ['BAD_ARGS']),
                 <<"200">> =>
                     emqx_mgmt_util:schema(resp_schema(),
-                                          <<"Create or update rule successfully">>)}},
+                                          <<"Update rule successfully">>)}},
         delete => #{
             description => <<"Delete a rule by given Id from all nodes in the cluster">>,
             parameters => [param_path_id()],