Merge pull request #7329 from DDDHuang/fix_api

fix: generate http api response code

apps/emqx/include/http_api.hrl

@@ -30,6 +30,7 @@
 -define(NO_DEFAULT_VALUE,         'NO_DEFAULT_VALUE').
 -define(DEPENDENCY_EXISTS,        'DEPENDENCY_EXISTS').
 -define(MESSAGE_ID_SCHEMA_ERROR,  'MESSAGE_ID_SCHEMA_ERROR').
+-define(INVALID_ID,               'INVALID_ID').
 
 %% Resource Not Found
 -define(NOT_FOUND,                'NOT_FOUND').
@@ -63,6 +64,7 @@
     , {'NO_DEFAULT_VALUE',          <<"Request parameters do not use default values">>}
     , {'DEPENDENCY_EXISTS',         <<"Resource is dependent by another resource">>}
     , {'MESSAGE_ID_SCHEMA_ERROR',   <<"Message ID parsing error">>}
+    , {'INVALID_ID',                <<"Bad ID schema">>}
     , {'MESSAGE_ID_NOT_FOUND',      <<"Message ID does not exist">>}
     , {'NOT_FOUND',                 <<"Resource was not found or does not exist">>}
     , {'CLIENTID_NOT_FOUND',        <<"Client ID was not found or does not exist">>}

apps/emqx_bridge/src/emqx_bridge_api.erl

@@ -267,7 +267,7 @@ schema("/bridges/:id") ->
             responses => #{
                 200 => get_response_body_schema(),
                 404 => error_schema('NOT_FOUND', "Bridge not found"),
-                400 => error_schema('BAD_REQUEST', "Update bridge failed")
+                400 => error_schema(['BAD_REQUEST', 'INVALID_ID'], "Update bridge failed")
             }
         },
         delete => #{
@@ -276,7 +276,8 @@ schema("/bridges/:id") ->
             description => <<"Delete a bridge by Id">>,
             parameters => [param_path_id()],
             responses => #{
-                204 => <<"Bridge deleted">>
+                204 => <<"Bridge deleted">>,
+                400 => error_schema(['INVALID_ID'], "Update bridge failed")
             }
         }
     };
@@ -294,8 +295,8 @@ schema("/bridges/:id/operation/:operation") ->
                 param_path_operation_cluster()
             ],
             responses => #{
-                500 => error_schema('INTERNAL_ERROR', "Operation Failed"),
+                200 => <<"Operation success">>,
-                200 => <<"Operation success">>
+                400 => error_schema('INVALID_ID', "Bad bridge ID")
             }
         }
     };
@@ -314,8 +315,8 @@ schema("/nodes/:node/bridges/:id/operation/:operation") ->
                 param_path_operation_on_node()
             ],
             responses => #{
-                500 => error_schema('INTERNAL_ERROR', "Operation Failed"),
+                200 => <<"Operation success">>,
-                200 => <<"Operation success">>
+                400 => error_schema('INVALID_ID', "Bad bridge ID")
             }
         }
     }.

apps/emqx_connector/src/emqx_connector_api.erl

@@ -125,7 +125,7 @@ schema("/connectors_test") ->
         'operationId' => '/connectors_test',
         post => #{
             tags => [<<"connectors">>],
-            description => <<"Test creating a new connector by given Id <br>"
+            desc => <<"Test creating a new connector by given Id <br>"
                              "The ID must be of format '{type}:{name}'">>,
             summary => <<"Test creating connector">>,
             'requestBody' => post_request_body_schema(),
@@ -141,7 +141,7 @@ schema("/connectors") ->
         'operationId' => '/connectors',
         get => #{
             tags => [<<"connectors">>],
-            description => <<"List all connectors">>,
+            desc => <<"List all connectors">>,
             summary => <<"List connectors">>,
             responses => #{
                 200 => emqx_dashboard_swagger:schema_with_example(
@@ -151,7 +151,7 @@ schema("/connectors") ->
         },
         post => #{
             tags => [<<"connectors">>],
-            description => <<"Create a new connector">>,
+            desc => <<"Create a new connector">>,
             summary => <<"Create connector">>,
             'requestBody' => post_request_body_schema(),
             responses => #{
@@ -166,33 +166,36 @@ schema("/connectors/:id") ->
         'operationId' => '/connectors/:id',
         get => #{
             tags => [<<"connectors">>],
-            description => <<"Get the connector by Id">>,
+            desc => <<"Get the connector by Id">>,
             summary => <<"Get connector">>,
             parameters => param_path_id(),
             responses => #{
                 200 => get_response_body_schema(),
-                404 => error_schema(['NOT_FOUND'], "Connector not found")
+                404 => error_schema(['NOT_FOUND'], "Connector not found"),
+                400 => error_schema(['INVALID_ID'], "Bad connector ID")
             }
         },
         put => #{
             tags => [<<"connectors">>],
-            description => <<"Update an existing connector by Id">>,
+            desc => <<"Update an existing connector by Id">>,
             summary => <<"Update connector">>,
             parameters => param_path_id(),
             'requestBody' => put_request_body_schema(),
             responses => #{
                 200 => get_response_body_schema(),
-                404 => error_schema(['NOT_FOUND'], "Connector not found")
+                404 => error_schema(['NOT_FOUND'], "Connector not found"),
+                400 => error_schema(['INVALID_ID'], "Bad connector ID")
             }},
         delete => #{
             tags => [<<"connectors">>],
-            description => <<"Delete a connector by Id">>,
+            desc => <<"Delete a connector by Id">>,
             summary => <<"Delete connector">>,
             parameters => param_path_id(),
             responses => #{
                 204 => <<"Delete connector successfully">>,
                 403 => error_schema(['DEPENDENCY_EXISTS'], "Cannot remove dependent connector"),
-                404 => error_schema(['NOT_FOUND'], "Delete failed, not found")
+                404 => error_schema(['NOT_FOUND'], "Delete failed, not found"),
+                400 => error_schema(['INVALID_ID'], "Bad connector ID")
             }}
     }.
 

apps/emqx_dashboard/src/emqx_dashboard_api.erl

@@ -48,7 +48,7 @@ schema("/login") ->
         'operationId' => login,
         post => #{
             tags => [<<"dashboard">>],
-            description => <<"Dashboard Auth">>,
+            desc => <<"Dashboard Auth">>,
             summary => <<"Dashboard Auth">>,
             'requestBody' => [
                 {username, mk(binary(),
@@ -77,7 +77,7 @@ schema("/logout") ->
         'operationId' => logout,
         post => #{
             tags => [<<"dashboard">>],
-            description => <<"Dashboard User logout">>,
+            desc => <<"Dashboard User logout">>,
             'requestBody' => [
                 {username, mk(binary(),
                     #{desc => <<"The User for which to create the token.">>,
@@ -93,7 +93,7 @@ schema("/users") ->
         'operationId' => users,
         get => #{
             tags => [<<"dashboard">>],
-            description => <<"Get dashboard users list">>,
+            desc => <<"Get dashboard users list">>,
             responses => #{
                 200 => mk( array(ref(?MODULE, user))
                          , #{desc => "User lists"})
@@ -101,7 +101,7 @@ schema("/users") ->
         },
         post => #{
             tags => [<<"dashboard">>],
-            description => <<"Create dashboard users">>,
+            desc => <<"Create dashboard users">>,
             'requestBody' => fields(user_password),
             responses => #{
                 200 => mk( ref(?MODULE, user)
@@ -118,7 +118,7 @@ schema("/users/:username") ->
         'operationId' => user,
         put => #{
             tags => [<<"dashboard">>],
-            description => <<"Update dashboard users">>,
+            desc => <<"Update dashboard users">>,
             parameters => [{username, mk(binary(),
                 #{in => path, example => <<"admin">>})}],
             'requestBody' => [
@@ -138,7 +138,7 @@ schema("/users/:username") ->
         },
         delete => #{
             tags => [<<"dashboard">>],
-            description => <<"Delete dashboard users">>,
+            desc => <<"Delete dashboard users">>,
             parameters => [{username, mk(binary(),
                 #{in => path, example => <<"admin">>})}],
             responses => #{
@@ -156,7 +156,7 @@ schema("/users/:username/change_pwd") ->
         'operationId' => change_pwd,
         put => #{
             tags => [<<"dashboard">>],
-            description => <<"Update dashboard users password">>,
+            desc => <<"Update dashboard users password">>,
             parameters => [{username, mk(binary(),
                 #{in => path, required => true, example => <<"admin">>})}],
             'requestBody' => [
@@ -183,7 +183,8 @@ fields(user) ->
                 #{desc => <<"username">>, example => "emqx"})}
     ];
 fields(user_password) ->
-    fields(user) ++ [{password, mk(binary(), #{desc => "Password", example => <<"public">>})}].
+    fields(user) ++
+        [{password, mk(binary(), #{desc => "Password", example => <<"public">>})}].
 
 login(post, #{body := Params}) ->
     Username = maps:get(<<"username">>, Params),

apps/emqx_dashboard/src/emqx_dashboard_monitor_api.erl

@@ -35,7 +35,7 @@ schema("/monitor") ->
         'operationId' => monitor,
         get => #{
             tags => [dashboard],
-            description => <<"List monitor data.">>,
+            desc => <<"List monitor data.">>,
             parameters => [parameter_latest()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(sampler)), #{}),
@@ -49,7 +49,7 @@ schema("/monitor/nodes/:node") ->
         'operationId' => monitor,
         get => #{
             tags => [dashboard],
-            description => <<"List the monitor data on the node.">>,
+            desc => <<"List the monitor data on the node.">>,
             parameters => [parameter_node(), parameter_latest()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:array(hoconsc:ref(sampler)), #{}),
@@ -63,7 +63,7 @@ schema("/monitor_current") ->
         'operationId' => monitor_current,
         get => #{
             tags => [dashboard],
-            description => <<"Current status. Gauge and rate.">>,
+            desc => <<"Current status. Gauge and rate.">>,
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{})
             }
@@ -75,7 +75,7 @@ schema("/monitor_current/nodes/:node") ->
         'operationId' => monitor_current,
         get => #{
             tags => [dashboard],
-            description => <<"Node current status. Gauge and rate.">>,
+            desc => <<"Node current status. Gauge and rate.">>,
             parameters => [parameter_node()],
             responses => #{
                 200 => hoconsc:mk(hoconsc:ref(sampler_current), #{}),
@@ -89,7 +89,7 @@ parameter_latest() ->
         in => query,
         required => false,
         example => 5 * 60,
-        description => <<"The latest N seconds data. Like 300 for 5 min.">>
+        desc => <<"The latest N seconds data. Like 300 for 5 min.">>
     },
     {latest, hoconsc:mk(range(1, inf), Info)}.
 
@@ -98,7 +98,7 @@ parameter_node() ->
         in => path,
         required => true,
         example => node(),
-        description => <<"EMQX node name.">>
+        desc => <<"EMQX node name.">>
     },
     {node, hoconsc:mk(binary(), Info)}.
 

apps/emqx_dashboard/src/emqx_dashboard_swagger.erl

@@ -247,7 +247,7 @@ meta_to_spec(Meta, Module, Options) ->
     {RequestBody, Refs2} = request_body(maps:get('requestBody', Meta, []), Module),
     {Responses, Refs3} = responses(maps:get(responses, Meta, #{}), Module, Options),
     {
-        to_spec(Meta, Params, RequestBody, Responses),
+        generate_method_desc(to_spec(Meta, Params, RequestBody, Responses)),
         lists:usort(Refs1 ++ Refs2 ++ Refs3)
     }.
 
@@ -258,6 +258,14 @@ to_spec(Meta, Params, RequestBody, Responses) ->
     Spec = to_spec(Meta, Params, [], Responses),
     maps:put('requestBody', RequestBody, Spec).
 
+generate_method_desc(Spec0 = #{desc := Desc}) ->
+    Spec = maps:remove(desc, Spec0),
+    Spec#{description => to_bin(Desc)};
+generate_method_desc(Spec = #{description := Desc}) ->
+    Spec#{description => to_bin(Desc)};
+generate_method_desc(Spec) ->
+    Spec.
+
 parameters(Params, Module) ->
     {SpecList, AllRefs} =
         lists:foldl(fun(Param, {Acc, RefsAcc}) ->
@@ -298,7 +306,7 @@ trans_required(Spec, _, path) -> Spec#{required => true};
 trans_required(Spec, _, _) -> Spec.
 
 trans_desc(Init, Hocon, Func, Name) ->
-    Spec0 =  trans_desc(Init, Hocon),
+    Spec0 = trans_desc(Init, Hocon),
     case Func =:= fun hocon_schema_to_spec/2 of
         true -> Spec0;
         false ->
@@ -311,7 +319,13 @@ trans_desc(Init, Hocon, Func, Name) ->
 
 trans_desc(Spec, Hocon) ->
     case hocon_schema:field_schema(Hocon, desc) of
-        undefined -> Spec;
+        undefined ->
+            case hocon_schema:field_schema(Hocon, description) of
+                undefined ->
+                    Spec;
+                Desc ->
+                    Spec#{description => to_bin(Desc)}
+            end;
         Desc -> Spec#{description => to_bin(Desc)}
     end.
 
@@ -446,12 +460,12 @@ typename_to_spec("string()", _Mod) -> #{type => string, example => <<"string-exa
 typename_to_spec("atom()", _Mod) -> #{type => string, example => atom};
 typename_to_spec("epoch_second()", _Mod) ->
     #{<<"oneOf">> => [
-        #{type => integer, example => 1640995200, desc => <<"epoch-second">>},
+        #{type => integer, example => 1640995200, description => <<"epoch-second">>},
         #{type => string, example => <<"2022-01-01T00:00:00.000Z">>, format => <<"date-time">>}]
         };
 typename_to_spec("epoch_millisecond()", _Mod) ->
     #{<<"oneOf">> => [
-        #{type => integer, example => 1640995200000, desc => <<"epoch-millisecond">>},
+        #{type => integer, example => 1640995200000, description => <<"epoch-millisecond">>},
         #{type => string, example => <<"2022-01-01T00:00:00.000Z">>, format => <<"date-time">>}]
     };
 typename_to_spec("duration()", _Mod) -> #{type => string, example => <<"12m">>};

apps/emqx_dashboard/test/emqx_swagger_parameter_SUITE.erl

@@ -287,7 +287,9 @@ schema("/test/in/query") ->
             parameters => [
                 {per_page,
                     mk(range(1, 100),
-                        #{in => query, desc => <<"results per page (max 100)">>, example => 1})},
+                        #{in => query,
+                        desc => <<"results per page (max 100)">>,
+                        example => 1})},
                 {qos, mk(emqx_schema:qos(), #{in => query, desc => <<"QOS">>})}
             ],
             responses => #{200 => <<"ok">>}
@@ -325,7 +327,7 @@ schema("/test/in/mix/:state") ->
         operationId => test,
         post => #{
             tags => [tags, good],
-            description => <<"good description">>,
+            desc => <<"good description">>,
             summary => <<"good summary">>,
             security => [],
             deprecated => true,

apps/emqx_exhook/src/emqx_exhook_api.erl

@@ -52,11 +52,11 @@ schema(("/exhooks")) ->
     #{
       'operationId' => exhooks,
       get => #{tags => ?TAGS,
-               description => <<"List all servers">>,
+               desc => <<"List all servers">>,
                responses => #{200 => mk(array(ref(detail_server_info)), #{})}
               },
       post => #{tags => ?TAGS,
-                description => <<"Add a servers">>,
+                desc => <<"Add a servers">>,
                 'requestBody' => server_conf_schema(),
                 responses => #{201 => mk(ref(detail_server_info), #{}),
                                500 => error_codes([?BAD_RPC], <<"Bad RPC">>)
@@ -67,14 +67,14 @@ schema(("/exhooks")) ->
 schema("/exhooks/:name") ->
     #{'operationId' => action_with_name,
       get => #{tags => ?TAGS,
-               description => <<"Get the detail information of server">>,
+               desc => <<"Get the detail information of server">>,
                parameters => params_server_name_in_path(),
                responses => #{200 => mk(ref(detail_server_info), #{}),
                               400 => error_codes([?BAD_REQUEST], <<"Bad Request">>)
                              }
               },
       put => #{tags => ?TAGS,
-               description => <<"Update the server">>,
+               desc => <<"Update the server">>,
                parameters => params_server_name_in_path(),
                'requestBody' => server_conf_schema(),
                responses => #{200 => <<>>,
@@ -83,7 +83,7 @@ schema("/exhooks/:name") ->
                              }
               },
       delete => #{tags => ?TAGS,
-                  description => <<"Delete the server">>,
+                  desc => <<"Delete the server">>,
                   parameters => params_server_name_in_path(),
                   responses => #{204 => <<>>,
                                  500 => error_codes([?BAD_RPC], <<"Bad RPC">>)
@@ -94,7 +94,7 @@ schema("/exhooks/:name") ->
 schema("/exhooks/:name/hooks") ->
     #{'operationId' => server_hooks,
       get => #{tags => ?TAGS,
-               description => <<"Get the hooks information of server">>,
+               desc => <<"Get the hooks information of server">>,
                parameters => params_server_name_in_path(),
                responses => #{200 => mk(array(ref(list_hook_info)), #{}),
                               400 => error_codes([?BAD_REQUEST], <<"Bad Request">>)
@@ -105,7 +105,7 @@ schema("/exhooks/:name/hooks") ->
 schema("/exhooks/:name/move") ->
     #{'operationId' => move,
       post => #{tags => ?TAGS,
-                description =>
+                desc =>
                     <<"Move the server.\n",
                       "NOTE: The position should be \"front|rear|before:{name}|after:{name}\"\n">>,
                 parameters => params_server_name_in_path(),
@@ -241,7 +241,6 @@ move(post, #{bindings := #{name := Name}, body := #{<<"position">> := RawPositio
                 {ok, ok} ->
                     {204};
                 {ok, not_found} ->
-                    %% TODO: unify status code
                     {400, #{code => <<"BAD_REQUEST">>,
                             message => <<"Server not found">>
                            }};

apps/emqx_gateway/include/emqx_gateway_http.hrl

@@ -16,11 +16,12 @@
 
 -define(BAD_REQUEST, 'BAD_REQUEST').
 -define(NOT_FOUND, 'NOT_FOUND').
+-define(RESOURCE_NOT_FOUND, 'RESOURCE_NOT_FOUND').
 -define(INTERNAL_ERROR, 'INTERNAL_SERVER_ERROR').
 
 -define(STANDARD_RESP(R),
         R#{ 400 => emqx_dashboard_swagger:error_codes(
                      [?BAD_REQUEST], <<"Bad request">>)
           , 404 => emqx_dashboard_swagger:error_codes(
-                     [?NOT_FOUND], <<"Not Found">>)
+                     [?NOT_FOUND, ?RESOURCE_NOT_FOUND], <<"Not Found">>)
          }).

apps/emqx_gateway/src/coap/emqx_coap_api.erl

@@ -46,7 +46,7 @@ paths() ->
 schema(?PREFIX ++ "/request") ->
     #{operationId => request,
       post => #{ tags => [<<"gateway|coap">>]
-               , description => <<"Send a CoAP request message to the client">>
+               , desc => <<"Send a CoAP request message to the client">>
                , parameters => request_parameters()
                , requestBody => request_body()
                , responses => #{200 => coap_message(),

apps/emqx_gateway/src/emqx_gateway_api.erl

@@ -44,7 +44,6 @@
 %% http handlers
 -export([ gateway/2
         , gateway_insta/2
-        , gateway_insta_stats/2
         ]).
 
 %%--------------------------------------------------------------------
@@ -57,7 +56,6 @@ api_spec() ->
 paths() ->
     [ "/gateway"
     , "/gateway/:name"
-    , "/gateway/:name/stats"
     ].
 
 %%--------------------------------------------------------------------
@@ -140,9 +138,6 @@ gateway_insta(put, #{body := GwConf0,
         end
     end).
 
-gateway_insta_stats(get, _Req) ->
-    return_http_error(401, "Implement it later (maybe 5.1)").
-
 %%--------------------------------------------------------------------
 %% Swagger defines
 %%--------------------------------------------------------------------
@@ -150,7 +145,7 @@ gateway_insta_stats(get, _Req) ->
 schema("/gateway") ->
     #{ 'operationId' => gateway,
        get =>
-         #{ description => <<"Get gateway list">>
+         #{ desc => <<"Get gateway list">>
           , parameters => params_gateway_status_in_qs()
           , responses =>
               ?STANDARD_RESP(
@@ -159,7 +154,7 @@ schema("/gateway") ->
                             examples_gateway_overview())})
           },
        post =>
-         #{ description => <<"Load a gateway">>
+         #{ desc => <<"Load a gateway">>
           %% TODO: distinguish create & response swagger schema
           , 'requestBody' => schema_gateways_conf()
           , responses =>
@@ -169,37 +164,24 @@ schema("/gateway") ->
 schema("/gateway/:name") ->
     #{ 'operationId' => gateway_insta,
        get =>
-         #{ description => <<"Get the gateway configurations">>
+         #{ desc => <<"Get the gateway configurations">>
           , parameters => params_gateway_name_in_path()
           , responses =>
               ?STANDARD_RESP(#{200 => schema_gateways_conf()})
           },
        delete =>
-         #{ description => <<"Delete/Unload the gateway">>
+         #{ desc => <<"Delete/Unload the gateway">>
           , parameters => params_gateway_name_in_path()
           , responses =>
               ?STANDARD_RESP(#{204 => <<"Deleted">>})
           },
        put =>
-         #{ description => <<"Update the gateway configurations/status">>
+         #{ desc => <<"Update the gateway configurations/status">>
           , parameters => params_gateway_name_in_path()
           , 'requestBody' => schema_update_gateways_conf()
           , responses =>
               ?STANDARD_RESP(#{200 => schema_gateways_conf()})
           }
-     };
-schema("/gateway/:name/stats") ->
-    #{ 'operationId' => gateway_insta_stats,
-       get =>
-         #{ description => <<"Get gateway Statistic">>
-          , parameters => params_gateway_name_in_path()
-          , responses =>
-              ?STANDARD_RESP(
-                 #{200 => emqx_dashboard_swagger:schema_with_examples(
-                           ref(gateway_stats),
-                           examples_gateway_stats())
-                  })
-          }
      }.
 
 %%--------------------------------------------------------------------
@@ -623,6 +605,3 @@ examples_update_gateway_confs() ->
              }
          }
      }.
-
-examples_gateway_stats() ->
-    #{}.

apps/emqx_gateway/src/emqx_gateway_api_authn.erl

@@ -159,7 +159,7 @@ parse_qstring(Qs) ->
 schema("/gateway/:name/authentication") ->
     #{ 'operationId' => authn,
        get =>
-         #{ description => <<"Get the gateway authentication">>
+         #{ desc => <<"Get the gateway authentication">>
           , parameters => params_gateway_name_in_path()
           , responses =>
               ?STANDARD_RESP(
@@ -168,21 +168,21 @@ schema("/gateway/:name/authentication") ->
                   })
           },
        put =>
-         #{ description => <<"Update authentication for the gateway">>
+         #{ desc => <<"Update authentication for the gateway">>
           , parameters => params_gateway_name_in_path()
           , 'requestBody' => schema_authn()
           , responses =>
               ?STANDARD_RESP(#{200 => schema_authn()})
           },
        post =>
-         #{ description => <<"Add authentication for the gateway">>
+         #{ desc => <<"Add authentication for the gateway">>
           , parameters => params_gateway_name_in_path()
           , 'requestBody' => schema_authn()
           , responses =>
               ?STANDARD_RESP(#{201 => schema_authn()})
           },
        delete =>
-         #{ description => <<"Remove the gateway authentication">>
+         #{ desc => <<"Remove the gateway authentication">>
           , parameters => params_gateway_name_in_path()
           , responses =>
               ?STANDARD_RESP(#{204 => <<"Deleted">>})
@@ -191,7 +191,7 @@ schema("/gateway/:name/authentication") ->
 schema("/gateway/:name/authentication/users") ->
     #{ 'operationId' => users
      , get =>
-         #{ description => <<"Get the users for the authentication">>
+         #{ desc => <<"Get the users for the authentication">>
           , parameters => params_gateway_name_in_path() ++
                           params_paging_in_qs() ++
                           params_fuzzy_in_qs()
@@ -203,7 +203,7 @@ schema("/gateway/:name/authentication/users") ->
                   })
           },
        post =>
-         #{ description => <<"Add user for the authentication">>
+         #{ desc => <<"Add user for the authentication">>
           , parameters => params_gateway_name_in_path()
           , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                                ref(emqx_authn_api, request_user_create),
@@ -219,7 +219,7 @@ schema("/gateway/:name/authentication/users") ->
 schema("/gateway/:name/authentication/users/:uid") ->
     #{ 'operationId' => users_insta
       , get =>
-          #{ description => <<"Get user info from the gateway "
+          #{ desc => <<"Get user info from the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_userid_in_path()
@@ -231,7 +231,7 @@ schema("/gateway/:name/authentication/users/:uid") ->
                    })
            },
         put =>
-          #{ description => <<"Update the user info for the gateway "
+          #{ desc => <<"Update the user info for the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_userid_in_path()
@@ -246,7 +246,7 @@ schema("/gateway/:name/authentication/users/:uid") ->
                    })
            },
         delete =>
-          #{ description => <<"Delete the user for the gateway "
+          #{ desc => <<"Delete the user for the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_userid_in_path()
@@ -257,7 +257,7 @@ schema("/gateway/:name/authentication/users/:uid") ->
 schema("/gateway/:name/authentication/import_users") ->
     #{ 'operationId' => import_users
      , post =>
-         #{ description => <<"Import users into the gateway authentication">>
+         #{ desc => <<"Import users into the gateway authentication">>
           , parameters => params_gateway_name_in_path()
           , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                              ref(emqx_authn_api, request_import_users),

apps/emqx_gateway/src/emqx_gateway_api_clients.erl

@@ -403,7 +403,7 @@ conn_state_to_connected(_) -> false.
 schema("/gateway/:name/clients") ->
     #{ 'operationId' => clients
      , get =>
-        #{ description => <<"Get the gateway client list">>
+        #{ desc => <<"Get the gateway client list">>
          , parameters => params_client_query()
          , responses =>
             ?STANDARD_RESP(#{200 => schema_client_list()})
@@ -412,13 +412,13 @@ schema("/gateway/:name/clients") ->
 schema("/gateway/:name/clients/:clientid") ->
     #{ 'operationId' => clients_insta
      , get =>
-        #{ description => <<"Get the gateway client information">>
+        #{ desc => <<"Get the gateway client information">>
          , parameters => params_client_insta()
          , responses =>
             ?STANDARD_RESP(#{200 => schema_client()})
          }
      , delete =>
-        #{ description => <<"Kick out the gateway client">>
+        #{ desc => <<"Kick out the gateway client">>
          , parameters => params_client_insta()
          , responses =>
             ?STANDARD_RESP(#{204 => <<"Kicked">>})
@@ -427,7 +427,7 @@ schema("/gateway/:name/clients/:clientid") ->
 schema("/gateway/:name/clients/:clientid/subscriptions") ->
     #{ 'operationId' => subscriptions
      , get =>
-        #{ description => <<"Get the gateway client subscriptions">>
+        #{ desc => <<"Get the gateway client subscriptions">>
          , parameters => params_client_insta()
          , responses =>
             ?STANDARD_RESP(
@@ -436,7 +436,7 @@ schema("/gateway/:name/clients/:clientid/subscriptions") ->
                           examples_subsctiption_list())})
          }
      , post =>
-        #{ description => <<"Create a subscription membership">>
+        #{ desc => <<"Create a subscription membership">>
          , parameters => params_client_insta()
          , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                             ref(subscription),
@@ -451,7 +451,7 @@ schema("/gateway/:name/clients/:clientid/subscriptions") ->
 schema("/gateway/:name/clients/:clientid/subscriptions/:topic") ->
     #{ 'operationId' => subscriptions
      , delete =>
-        #{ description => <<"Delete a subscriptions membership">>
+        #{ desc => <<"Delete a subscriptions membership">>
          , parameters => params_topic_name_in_path() ++ params_client_insta()
          , responses =>
             ?STANDARD_RESP(#{204 => <<"Unsubscribed">>})

apps/emqx_gateway/src/emqx_gateway_api_listeners.erl

@@ -221,7 +221,7 @@ page_pramas(Qs) ->
 schema("/gateway/:name/listeners") ->
     #{ 'operationId' => listeners,
        get =>
-         #{ description => <<"Get the gateway listeners">>
+         #{ desc => <<"Get the gateway listeners">>
           , parameters => params_gateway_name_in_path()
           , responses =>
               ?STANDARD_RESP(
@@ -231,7 +231,7 @@ schema("/gateway/:name/listeners") ->
                   })
           },
        post =>
-         #{ description => <<"Create the gateway listener">>
+         #{ desc => <<"Create the gateway listener">>
           , parameters => params_gateway_name_in_path()
           %% XXX: How to distinguish the different listener supported by
           %% different types of gateways?
@@ -249,7 +249,7 @@ schema("/gateway/:name/listeners") ->
 schema("/gateway/:name/listeners/:id") ->
     #{ 'operationId' => listeners_insta,
        get =>
-         #{ description => <<"Get the gateway listener configurations">>
+         #{ desc => <<"Get the gateway listener configurations">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , responses =>
@@ -260,14 +260,14 @@ schema("/gateway/:name/listeners/:id") ->
                   })
            },
        delete =>
-         #{ description => <<"Delete the gateway listener">>
+         #{ desc => <<"Delete the gateway listener">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , responses =>
               ?STANDARD_RESP(#{204 => <<"Deleted">>})
            },
        put =>
-         #{ description => <<"Update the gateway listener">>
+         #{ desc => <<"Update the gateway listener">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@@ -284,7 +284,7 @@ schema("/gateway/:name/listeners/:id") ->
 schema("/gateway/:name/listeners/:id/authentication") ->
     #{ 'operationId' => listeners_insta_authn,
        get =>
-         #{ description => <<"Get the listener's authentication info">>
+         #{ desc => <<"Get the listener's authentication info">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , responses =>
@@ -294,7 +294,7 @@ schema("/gateway/:name/listeners/:id/authentication") ->
                   })
           },
        post =>
-         #{ description => <<"Add authentication for the listener">>
+         #{ desc => <<"Add authentication for the listener">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , 'requestBody' => schema_authn()
@@ -302,7 +302,7 @@ schema("/gateway/:name/listeners/:id/authentication") ->
                ?STANDARD_RESP(#{201 => schema_authn()})
           },
        put =>
-         #{ description => <<"Update authentication for the listener">>
+         #{ desc => <<"Update authentication for the listener">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , 'requestBody' => schema_authn()
@@ -310,7 +310,7 @@ schema("/gateway/:name/listeners/:id/authentication") ->
               ?STANDARD_RESP(#{200 => schema_authn()})
           },
        delete =>
-         #{ description => <<"Remove authentication for the listener">>
+         #{ desc => <<"Remove authentication for the listener">>
           , parameters => params_gateway_name_in_path()
                           ++ params_listener_id_in_path()
           , responses =>
@@ -320,7 +320,7 @@ schema("/gateway/:name/listeners/:id/authentication") ->
 schema("/gateway/:name/listeners/:id/authentication/users") ->
     #{ 'operationId' => users
      , get =>
-         #{ description => <<"Get the users for the authentication">>
+         #{ desc => <<"Get the users for the authentication">>
           , parameters => params_gateway_name_in_path() ++
                           params_listener_id_in_path() ++
                           params_paging_in_qs()
@@ -332,7 +332,7 @@ schema("/gateway/:name/listeners/:id/authentication/users") ->
                   })
           },
        post =>
-         #{ description => <<"Add user for the authentication">>
+         #{ desc => <<"Add user for the authentication">>
           , parameters => params_gateway_name_in_path() ++
                           params_listener_id_in_path()
           , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(
@@ -349,7 +349,7 @@ schema("/gateway/:name/listeners/:id/authentication/users") ->
 schema("/gateway/:name/listeners/:id/authentication/users/:uid") ->
     #{ 'operationId' => users_insta
       , get =>
-          #{ description => <<"Get user info from the gateway "
+          #{ desc => <<"Get user info from the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_listener_id_in_path() ++
@@ -362,7 +362,7 @@ schema("/gateway/:name/listeners/:id/authentication/users/:uid") ->
                    })
            },
         put =>
-          #{ description => <<"Update the user info for the gateway "
+          #{ desc => <<"Update the user info for the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_listener_id_in_path() ++
@@ -378,7 +378,7 @@ schema("/gateway/:name/listeners/:id/authentication/users/:uid") ->
                    })
            },
         delete =>
-          #{ description => <<"Delete the user for the gateway "
+          #{ desc => <<"Delete the user for the gateway "
                               "authentication">>
            , parameters => params_gateway_name_in_path() ++
                            params_listener_id_in_path() ++
@@ -390,7 +390,7 @@ schema("/gateway/:name/listeners/:id/authentication/users/:uid") ->
 schema("/gateway/:name/listeners/:id/authentication/import_users") ->
     #{ 'operationId' => import_users
      , post =>
-         #{ description => <<"Import users into the gateway authentication">>
+         #{ desc => <<"Import users into the gateway authentication">>
           , parameters => params_gateway_name_in_path() ++
                           params_listener_id_in_path()
           , 'requestBody' => emqx_dashboard_swagger:schema_with_examples(

apps/emqx_gateway/src/emqx_gateway_http.erl

@@ -305,13 +305,9 @@ reason2resp(R) ->
             return_http_error(400, Msg)
     end.
 
--spec return_http_error(integer(), any()) -> {integer(), binary()}.
+-spec return_http_error(integer(), any()) -> {integer(), atom(), binary()}.
 return_http_error(Code, Msg) ->
-    {Code, emqx_json:encode(
+    {Code, codestr(Code), emqx_gateway_utils:stringfy(Msg)}.
-             #{code => codestr(Code),
-               message => emqx_gateway_utils:stringfy(Msg)
-              })
-    }.
 
 -spec reason2msg({atom(), map()} | any()) -> error | string().
 reason2msg({badconf, #{key := Key, value := Value, reason := Reason}}) ->
@@ -362,9 +358,9 @@ reason2msg(_) ->
     error.
 
 codestr(400) -> 'BAD_REQUEST';
-codestr(401) -> 'NOT_SUPPORTED_NOW';
 codestr(404) -> 'RESOURCE_NOT_FOUND';
 codestr(405) -> 'METHOD_NOT_ALLOWED';
+codestr(409) -> 'NOT_SUPPORT';
 codestr(500) -> 'UNKNOW_ERROR';
 codestr(501) -> 'NOT_IMPLEMENTED'.
 

apps/emqx_gateway/src/lwm2m/emqx_lwm2m_api.erl

@@ -42,7 +42,7 @@ schema(?PATH("/lookup_cmd")) ->
         'operationId' => lookup_cmd,
         get => #{
             tags => [<<"lwm2m">>],
-            description => <<"Look up resource">>,
+            desc => <<"Look up resource">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@@ -66,7 +66,7 @@ schema(?PATH("/observe")) ->
         'operationId' => observe,
         post => #{
             tags => [<<"lwm2m">>],
-            description => <<"(cancel) observe resource">>,
+            desc => <<"(cancel) observe resource">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})},
@@ -84,7 +84,7 @@ schema(?PATH("/read")) ->
         'operationId' => read,
         post => #{
             tags => [<<"lwm2m">>],
-            description => <<"Send a read command to resource">>,
+            desc => <<"Send a read command to resource">>,
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},
                 {path, mk(binary(), #{in => query, required => true, example => "/3/0/7"})}
@@ -99,7 +99,7 @@ schema(?PATH("/write")) ->
     #{
         'operationId' => write,
         post => #{
-            description => <<"Send a write command to resource">>,
+            desc => <<"Send a write command to resource">>,
             tags => [<<"lwm2m">>],
             parameters => [
                 {clientid, mk(binary(), #{in => path, example => "urn:oma:lwm2m:oma:2"})},

apps/emqx_retainer/src/emqx_retainer_api.erl

@@ -55,7 +55,7 @@ schema(?PREFIX) ->
                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">>)
+                              400 => error_codes(['UPDATE_FAILED'], <<"Update config failed">>)
                              }
               }
      };
@@ -66,7 +66,7 @@ schema(?PREFIX ++ "/messages") ->
                description => <<"List retained messages">>,
                parameters => page_params(),
                responses => #{200 => mk(array(ref(message_summary)), #{desc => "The result list"}),
-                              405 => error_codes(['ACTION_NOT_ALLOWED'], <<"Unsupported backend">>)
+                              400 => error_codes(['BAD_REQUEST'], <<"Unsupported backend">>)
                              }
               }
         };
@@ -78,14 +78,14 @@ schema(?PREFIX ++ "/message/:topic") ->
                parameters => parameters(),
                responses => #{200 => mk(ref(message), #{desc => "Details of the message"}),
                               404 => error_codes(['NOT_FOUND'], <<"Viewed message doesn't exist">>),
-                              405 => error_codes(['ACTION_NOT_ALLOWED'], <<"Unsupported backend">>)
+                              400 => error_codes(['BAD_REQUEST'], <<"Unsupported backend">>)
                              }
               },
       delete => #{tags => ?TAGS,
                   description => <<"Delete matching messages">>,
                   parameters => parameters(),
                   responses => #{204 => <<>>,
-                                 405 => error_codes(['ACTION_NOT_ALLOWED'],
+                                 400 => error_codes(['BAD_REQUEST'],
                                                     <<"Unsupported backend">>)
                                 }
                  }
@@ -191,8 +191,5 @@ check_backend(Type, Params, Cont) ->
         built_in_database ->
             Cont(Type, Params);
         _ ->
-            {405,
+            {400, 'BAD_REQUEST', <<"This API only support built in database">>}
-             #{code => <<"ACTION_NOT_ALLOWED">>,
-               message => <<"This API only for built in database">>}
-            }
     end.

apps/emqx_slow_subs/src/emqx_slow_subs_api.erl

@@ -129,8 +129,13 @@ settings(get, _) ->
     {200, emqx:get_raw_config([slow_subs], #{})};
 
 settings(put, #{body := Body}) ->
-    _ = emqx_slow_subs:update_settings(Body),
+    case emqx_slow_subs:update_settings(Body) of
-    {200, emqx:get_raw_config([slow_subs], #{})}.
+        {ok, #{config := NewConf}} ->
+            {200, NewConf};
+        {error, Reason} ->
+            Message = list_to_binary(io_lib:format("Update slow subs config failed ~p", [Reason])),
+            {400, 'BAD_REQUEST', Message}
+    end.
 
 rpc_call(Fun) ->
     Nodes = mria_mnesia:running_nodes(),