Merge pull request #12398 from lafirest/feat/api-docs

feat(dashboard): expose the `swagger_support` option

apps/emqx_dashboard/src/emqx_dashboard.erl

@@ -76,7 +76,8 @@ start_listeners(Listeners) ->
         security => [#{'basicAuth' => []}, #{'bearerAuth' => []}],
         swagger_global_spec => GlobalSpec,
         dispatch => dispatch(),
-        middlewares => [?EMQX_MIDDLE, cowboy_router, cowboy_handler]
+        middlewares => [?EMQX_MIDDLE, cowboy_router, cowboy_handler],
+        swagger_support => emqx:get_config([dashboard, swagger_support], true)
     },
     {OkListeners, ErrListeners} =
         lists:foldl(

apps/emqx_dashboard/src/emqx_dashboard_listener.erl

@@ -149,12 +149,13 @@ remove_sensitive_data(Conf0) ->
 post_config_update(_, {change_i18n_lang, _}, _NewConf, _OldConf, _AppEnvs) ->
     delay_job(regenerate);
 post_config_update(_, _Req, NewConf, OldConf, _AppEnvs) ->
+    SwaggerSupport = diff_swagger_support(NewConf, OldConf),
     OldHttp = get_listener(http, OldConf),
     OldHttps = get_listener(https, OldConf),
     NewHttp = get_listener(http, NewConf),
     NewHttps = get_listener(https, NewConf),
-    {StopHttp, StartHttp} = diff_listeners(http, OldHttp, NewHttp),
+    {StopHttp, StartHttp} = diff_listeners(http, OldHttp, NewHttp, SwaggerSupport),
-    {StopHttps, StartHttps} = diff_listeners(https, OldHttps, NewHttps),
+    {StopHttps, StartHttps} = diff_listeners(https, OldHttps, NewHttps, SwaggerSupport),
     Stop = maps:merge(StopHttp, StopHttps),
     Start = maps:merge(StartHttp, StartHttps),
     delay_job({update_listeners, Stop, Start}).
@@ -168,10 +169,16 @@ delay_job(Msg) ->
 get_listener(Type, Conf) ->
     emqx_utils_maps:deep_get([listeners, Type], Conf, undefined).
 
-diff_listeners(_, Listener, Listener) -> {#{}, #{}};
+diff_swagger_support(NewConf, OldConf) ->
-diff_listeners(Type, undefined, Start) -> {#{}, #{Type => Start}};
+    maps:get(swagger_support, NewConf, true) =:=
-diff_listeners(Type, Stop, undefined) -> {#{Type => Stop}, #{}};
+        maps:get(swagger_support, OldConf, true).
-diff_listeners(Type, Stop, Start) -> {#{Type => Stop}, #{Type => Start}}.
+
+diff_listeners(_, undefined, undefined, _) -> {#{}, #{}};
+diff_listeners(_, Listener, Listener, true) -> {#{}, #{}};
+diff_listeners(Type, undefined, Start, _) -> {#{}, #{Type => Start}};
+diff_listeners(Type, Stop, undefined, _) -> {#{Type => Stop}, #{}};
+diff_listeners(Type, Listener, Listener, false) -> {#{Type => Listener}, #{Type => Listener}};
+diff_listeners(Type, Stop, Start, _) -> {#{Type => Stop}, #{Type => Start}}.
 
 -define(DIR, <<"dashboard">>).
 

apps/emqx_dashboard/src/emqx_dashboard_schema.erl

@@ -56,6 +56,7 @@ fields("dashboard") ->
                 }
             )},
         {cors, fun cors/1},
+        {swagger_support, fun swagger_support/1},
         {i18n_lang, fun i18n_lang/1},
         {bootstrap_users_file,
             ?HOCON(
@@ -272,6 +273,11 @@ cors(required) -> false;
 cors(desc) -> ?DESC(cors);
 cors(_) -> undefined.
 
+swagger_support(type) -> boolean();
+swagger_support(default) -> true;
+swagger_support(desc) -> ?DESC(swagger_support);
+swagger_support(_) -> undefined.
+
 %% TODO: change it to string type
 %% It will be up to the dashboard package which languages to support
 i18n_lang(type) -> ?ENUM([en, zh]);

apps/emqx_dashboard/test/emqx_dashboard_SUITE.erl

@@ -31,6 +31,7 @@
 -include_lib("eunit/include/eunit.hrl").
 -include_lib("common_test/include/ct.hrl").
 -include_lib("emqx/include/emqx.hrl").
+-include_lib("snabbkaffe/include/snabbkaffe.hrl").
 -include("emqx_dashboard.hrl").
 
 -define(CONTENT_TYPE, "application/x-www-form-urlencoded").
@@ -188,6 +189,38 @@ t_swagger_json(_Config) ->
     ),
     ok.
 
+t_disable_swagger_json(_Config) ->
+    Url = ?HOST ++ "/api-docs/index.html",
+
+    ?assertMatch(
+        {ok, {{"HTTP/1.1", 200, "OK"}, __, _}},
+        httpc:request(get, {Url, []}, [], [{body_format, binary}])
+    ),
+
+    DashboardCfg = emqx:get_raw_config([dashboard]),
+    DashboardCfg2 = DashboardCfg#{<<"swagger_support">> => false},
+    emqx:update_config([dashboard], DashboardCfg2),
+    ?retry(
+        _Sleep = 1000,
+        _Attempts = 5,
+        ?assertMatch(
+            {ok, {{"HTTP/1.1", 404, "Not Found"}, _, _}},
+            httpc:request(get, {Url, []}, [], [{body_format, binary}])
+        )
+    ),
+
+    DashboardCfg3 = DashboardCfg#{<<"swagger_support">> => true},
+    emqx:update_config([dashboard], DashboardCfg3),
+    ?retry(
+        _Sleep0 = 1000,
+        _Attempts0 = 5,
+        ?assertMatch(
+            {ok, {{"HTTP/1.1", 200, "OK"}, __, _}},
+            httpc:request(get, {Url, []}, [], [{body_format, binary}])
+        )
+    ),
+    ok.
+
 t_cli(_Config) ->
     [mria:dirty_delete(?ADMIN, Admin) || Admin <- mnesia:dirty_all_keys(?ADMIN)],
     emqx_dashboard_cli:admins(["add", "username", "password_ww2"]),

changes/ce/feat-12398.en.md

@@ -0,0 +1 @@
+Exposed the `swagger_support` option in configuration for Dashboard to disable the swagger API document.

rel/i18n/emqx_dashboard_schema.hocon

@@ -143,4 +143,9 @@ ssl_options.desc:
 ssl_options.label:
 """SSL options"""
 
+swagger_support.desc:
+"""Enable or disable support for swagger API documentation."""
+
+swagger_support.label:
+"""Swagger Support"""
 }