Merge pull request #10195 from sstrigler/EMQX-8982-html-tags-are-displayed-in-http-api-doc

fix: add summary to schemas where description has html

apps/emqx_bridge/src/emqx_bridge_api.erl

@@ -438,7 +438,7 @@ schema("/nodes/:node/bridges/:id/:operation") ->
         'operationId' => '/nodes/:node/bridges/:id/:operation',
         post => #{
             tags => [<<"bridges">>],
-            summary => <<"Stop/Restart bridge">>,
+            summary => <<"Stop/restart bridge">>,
             description => ?DESC("desc_api8"),
             parameters => [
                 param_path_node(),

apps/emqx_exhook/i18n/emqx_exhook_api_i18n.conf

@@ -49,6 +49,10 @@ NOTE: The position should be \"front | rear | before:{name} | after:{name}"""
       zh: """移动 Exhook 服务器顺序。
 注意: 移动的参数只能是：front | rear | before:{name} | after:{name}"""
     }
+    label {
+      en: "Change order of execution for registered Exhook server"
+      zh: "改变已注册的Exhook服务器的执行顺序"
+    }
   }
 
   move_position {

apps/emqx_management/i18n/emqx_mgmt_api_publish_i18n.conf

@@ -2,8 +2,7 @@
 emqx_mgmt_api_publish {
     publish_api {
         desc {
-            en: """Publish one message.<br/>
+            en: """Possible HTTP status response codes are:<br/>
-Possible HTTP status response codes are:<br/>
 <code>200</code>: The message is delivered to at least one subscriber;<br/>
 <code>202</code>: No matched subscribers;<br/>
 <code>400</code>: Message is invalid. for example bad topic name, or QoS is out of range;<br/>
@@ -16,11 +15,14 @@ Possible HTTP status response codes are:<br/>
 400: 消息编码错误，如非法主题，或 QoS 超出范围等。<br/>
 503: 服务重启等过程中导致转发失败。"""
         }
+        label {
+            en: "Publish a message"
+            zh: "发布一条信息"
+        }
     }
     publish_bulk_api {
         desc {
-            en: """Publish a batch of messages.<br/>
+            en: """Possible HTTP response status code are:<br/>
-Possible HTTP response status code are:<br/>
 200: All messages are delivered to at least one subscriber;<br/>
 202: At least one message was not delivered to any subscriber;<br/>
 400: At least one message is invalid. For example bad topic name, or QoS is out of range;<br/>
@@ -41,6 +43,10 @@ result of each individual message in the batch."""
  <code>/publish</code> 是一样的。
 如果所有的消息都是合法的，那么 HTTP 返回的内容是一个 JSON 数组，每个元素代表了该消息转发的状态。"""
         }
+        label {
+            en: "Publish a batch of messages"
+            zh: "发布一批信息"
+        }
     }
 
     topic_name {

apps/emqx_management/i18n/emqx_mgmt_api_status_i18n.conf

@@ -22,6 +22,10 @@ emqx_mgmt_api_status {
           "GET `/status`端点（没有`/api/...`前缀）也是这个端点的一个别名，工作方式相同。"
           " 这个别名从v5.0.0开始就有了。"
     }
+    label {
+       en: "Service health check"
+       zh: "服务健康检查"
+    }
   }
 
   get_status_response200 {

apps/emqx_management/src/emqx_mgmt_api_configs.erl

@@ -119,6 +119,7 @@ schema("/configs_reset/:rootname") ->
                     "- For a config entry that has default value, this resets it to the default value;\n"
                     "- For a config entry that has no default value, an error 400 will be returned"
                 >>,
+            summary => <<"Reset config entry">>,
             %% We only return "200" rather than the new configs that has been changed, as
             %% the schema of the changed configs is depends on the request parameter
             %% `conf_path`, it cannot be defined here.

apps/emqx_management/src/emqx_mgmt_api_plugins.erl

@@ -68,10 +68,10 @@ schema("/plugins") ->
     #{
         'operationId' => list_plugins,
         get => #{
+            summary => <<"List all installed plugins">>,
             description =>
-                "List all install plugins.<br/>"
                 "Plugins are launched in top-down order.<br/>"
-                "Using `POST /plugins/{name}/move` to change the boot order.",
+                "Use `POST /plugins/{name}/move` to change the boot order.",
             tags => ?TAGS,
             responses => #{
                 200 => hoconsc:array(hoconsc:ref(plugin))
@@ -82,8 +82,9 @@ schema("/plugins/install") ->
     #{
         'operationId' => upload_install,
         post => #{
+            summary => <<"Install a new plugin">>,
             description =>
-                "Install a plugin(plugin-vsn.tar.gz)."
+                "Upload a plugin tarball (plugin-vsn.tar.gz)."
                 "Follow [emqx-plugin-template](https://github.com/emqx/emqx-plugin-template) "
                 "to develop plugin.",
             tags => ?TAGS,
@@ -112,7 +113,8 @@ schema("/plugins/:name") ->
     #{
         'operationId' => plugin,
         get => #{
-            description => "Describe a plugin according `release.json` and `README.md`.",
+            summary => <<"Get a plugin description">>,
+            description => "Describs plugin according to its `release.json` and `README.md`.",
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],
             responses => #{
@@ -121,7 +123,8 @@ schema("/plugins/:name") ->
             }
         },
         delete => #{
-            description => "Uninstall a plugin package.",
+            summary => <<"Delete a plugin">>,
+            description => "Uninstalls a previously uploaded plugin package.",
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],
             responses => #{
@@ -134,6 +137,7 @@ schema("/plugins/:name/:action") ->
     #{
         'operationId' => update_plugin,
         put => #{
+            summary => <<"Trigger action on an installed plugin">>,
             description =>
                 "start/stop a installed plugin.<br/>"
                 "- **start**: start the plugin.<br/>"
@@ -153,6 +157,7 @@ schema("/plugins/:name/move") ->
     #{
         'operationId' => update_boot_order,
         post => #{
+            summary => <<"Move plugin within plugin hiearchy">>,
             description => "Setting the boot order of plugins.",
             tags => ?TAGS,
             parameters => [hoconsc:ref(name)],

apps/emqx_management/src/emqx_mgmt_api_publish.erl

@@ -50,6 +50,7 @@ schema("/publish") ->
     #{
         'operationId' => publish,
         post => #{
+            summary => <<"Publish a message">>,
             description => ?DESC(publish_api),
             tags => [<<"Publish">>],
             'requestBody' => hoconsc:mk(hoconsc:ref(?MODULE, publish_message)),
@@ -65,6 +66,7 @@ schema("/publish/bulk") ->
     #{
         'operationId' => publish_batch,
         post => #{
+            summary => <<"Publish a batch of messages">>,
             description => ?DESC(publish_bulk_api),
             tags => [<<"Publish">>],
             'requestBody' => hoconsc:mk(hoconsc:array(hoconsc:ref(?MODULE, publish_message)), #{}),

changes/ce/fix-10195.en.md

@@ -0,0 +1 @@
+Add labels to API schemas where description contains HTML and breaks formatting of generated documentation otherwise.