From da37e01d32f9764c3937736ef0c7d3ab40af9a77 Mon Sep 17 00:00:00 2001
From: Russ Cam <russ.cam@elastic.co>
Date: Thu, 2 Apr 2020 10:40:50 +1000
Subject: [PATCH] Update rest API specs (#54252)

This commit updates the rest API specs to validate against a
JSON schema for the specifications. Most updates are to add
a description, whilst others fix typos and unify conventions
e.g. deprecations, descriptions, urls starting with /. The schema
conforms to draft-07 JSON schema.
---
 .../rest-api-spec/api/cat.aliases.json        |   2 +-
 .../rest-api-spec/api/cat.health.json         |  14 +-
 .../rest-api-spec/api/cat.indices.json        |   1 -
 .../rest-api-spec/api/cluster.health.json     |   1 -
 .../rest-api-spec/api/delete_by_query.json    |   3 +-
 .../rest-api-spec/api/get_script_context.json |   1 +
 .../api/get_script_languages.json             |   1 +
 .../rest-api-spec/api/indices.get_alias.json  |   2 +-
 .../api/indices.get_settings.json             |   5 +-
 .../api/snapshot.cleanup_repository.json      |   3 +-
 .../rest-api-spec/api/update_by_query.json    |   3 +-
 rest-api-spec/src/main/resources/schema.json  | 245 ++++++++++++++++++
 .../api/async_search.delete.json              |   3 +-
 .../rest-api-spec/api/async_search.get.json   |   3 +-
 .../api/async_search.submit.json              |   3 +-
 .../autoscaling.get_autoscaling_decision.json |   3 +-
 .../api/cat.ml_data_frame_analytics.json      |  17 +-
 .../rest-api-spec/api/cat.ml_datafeeds.json   |  17 +-
 .../rest-api-spec/api/cat.ml_jobs.json        |  17 +-
 .../api/cat.ml_trained_models.json            |  17 +-
 .../rest-api-spec/api/cat.transform.json      |  17 +-
 .../api/ccr.delete_auto_follow_pattern.json   |   3 +-
 .../rest-api-spec/api/ccr.follow.json         |   3 +-
 .../rest-api-spec/api/ccr.follow_info.json    |   3 +-
 .../rest-api-spec/api/ccr.follow_stats.json   |   3 +-
 .../api/ccr.forget_follower.json              |   3 +-
 .../api/ccr.get_auto_follow_pattern.json      |   3 +-
 .../api/ccr.pause_auto_follow_pattern.json    |   3 +-
 .../rest-api-spec/api/ccr.pause_follow.json   |   3 +-
 .../api/ccr.put_auto_follow_pattern.json      |   3 +-
 .../api/ccr.resume_auto_follow_pattern.json   |   3 +-
 .../rest-api-spec/api/ccr.resume_follow.json  |   3 +-
 .../rest-api-spec/api/ccr.stats.json          |   3 +-
 .../rest-api-spec/api/ccr.unfollow.json       |   3 +-
 ...transform_deprecated.delete_transform.json |   3 +-
 ...me_transform_deprecated.get_transform.json |   3 +-
 ...nsform_deprecated.get_transform_stats.json |   3 +-
 ...ransform_deprecated.preview_transform.json |   3 +-
 ...me_transform_deprecated.put_transform.json |  13 +-
 ..._transform_deprecated.start_transform.json |   3 +-
 ...e_transform_deprecated.stop_transform.json |   3 +-
 ...transform_deprecated.update_transform.json |  45 ++--
 .../api/enrich.delete_policy.json             |   3 +-
 .../api/enrich.execute_policy.json            |   3 +-
 .../rest-api-spec/api/enrich.get_policy.json  |   3 +-
 .../rest-api-spec/api/enrich.put_policy.json  |   3 +-
 .../rest-api-spec/api/enrich.stats.json       |   3 +-
 .../rest-api-spec/api/eql.search.json         |   3 +-
 .../rest-api-spec/api/graph.explore.json      |   3 +-
 .../api/ilm.delete_lifecycle.json             |   3 +-
 .../api/ilm.explain_lifecycle.json            |   3 +-
 .../rest-api-spec/api/ilm.get_lifecycle.json  |   3 +-
 .../rest-api-spec/api/ilm.get_status.json     |   3 +-
 .../rest-api-spec/api/ilm.move_to_step.json   |   3 +-
 .../rest-api-spec/api/ilm.put_lifecycle.json  |   3 +-
 .../rest-api-spec/api/ilm.remove_policy.json  |   3 +-
 .../rest-api-spec/api/ilm.retry.json          |   3 +-
 .../rest-api-spec/api/ilm.start.json          |   3 +-
 .../resources/rest-api-spec/api/ilm.stop.json |   3 +-
 .../rest-api-spec/api/indices.freeze.json     |   3 +-
 .../api/indices.reload_search_analyzers.json  |   3 +-
 .../rest-api-spec/api/indices.unfreeze.json   |   3 +-
 .../rest-api-spec/api/license.delete.json     |   3 +-
 .../rest-api-spec/api/license.get.json        |   7 +-
 .../api/license.get_basic_status.json         |   3 +-
 .../api/license.get_trial_status.json         |   3 +-
 .../rest-api-spec/api/license.post.json       |   3 +-
 .../api/license.post_start_basic.json         |   3 +-
 .../api/license.post_start_trial.json         |   3 +-
 .../api/migration.deprecations.json           |   3 +-
 .../rest-api-spec/api/ml.close_job.json       |   3 +-
 .../rest-api-spec/api/ml.delete_calendar.json |   3 +-
 .../api/ml.delete_calendar_event.json         |   3 +-
 .../api/ml.delete_calendar_job.json           |   3 +-
 .../api/ml.delete_data_frame_analytics.json   |   3 +-
 .../rest-api-spec/api/ml.delete_datafeed.json |   3 +-
 .../api/ml.delete_expired_data.json           |   3 +-
 .../rest-api-spec/api/ml.delete_filter.json   |   3 +-
 .../rest-api-spec/api/ml.delete_forecast.json |   5 +-
 .../rest-api-spec/api/ml.delete_job.json      |   3 +-
 .../api/ml.delete_model_snapshot.json         |   3 +-
 .../api/ml.delete_trained_model.json          |   3 +-
 .../api/ml.estimate_model_memory.json         |   3 +-
 .../api/ml.evaluate_data_frame.json           |   3 +-
 .../api/ml.explain_data_frame_analytics.json  |  35 ++-
 .../api/ml.find_file_structure.json           |   3 +-
 .../rest-api-spec/api/ml.flush_job.json       |   3 +-
 .../rest-api-spec/api/ml.forecast.json        |   3 +-
 .../rest-api-spec/api/ml.get_buckets.json     |   3 +-
 .../api/ml.get_calendar_events.json           |   3 +-
 .../rest-api-spec/api/ml.get_calendars.json   |   3 +-
 .../rest-api-spec/api/ml.get_categories.json  |   3 +-
 .../api/ml.get_data_frame_analytics.json      |   3 +-
 .../ml.get_data_frame_analytics_stats.json    |   3 +-
 .../api/ml.get_datafeed_stats.json            |   3 +-
 .../rest-api-spec/api/ml.get_datafeeds.json   |   3 +-
 .../rest-api-spec/api/ml.get_filters.json     |   3 +-
 .../rest-api-spec/api/ml.get_influencers.json |   6 +-
 .../rest-api-spec/api/ml.get_job_stats.json   |   3 +-
 .../rest-api-spec/api/ml.get_jobs.json        |   3 +-
 .../api/ml.get_model_snapshots.json           |   3 +-
 .../api/ml.get_overall_buckets.json           |   3 +-
 .../rest-api-spec/api/ml.get_records.json     |   9 +-
 .../api/ml.get_trained_models.json            |  21 +-
 .../api/ml.get_trained_models_stats.json      |   3 +-
 .../resources/rest-api-spec/api/ml.info.json  |   3 +-
 .../rest-api-spec/api/ml.open_job.json        |   3 +-
 .../api/ml.post_calendar_events.json          |   3 +-
 .../rest-api-spec/api/ml.post_data.json       |   3 +-
 .../api/ml.preview_datafeed.json              |   3 +-
 .../rest-api-spec/api/ml.put_calendar.json    |   3 +-
 .../api/ml.put_calendar_job.json              |   3 +-
 .../api/ml.put_data_frame_analytics.json      |   3 +-
 .../rest-api-spec/api/ml.put_datafeed.json    |   5 +-
 .../rest-api-spec/api/ml.put_filter.json      |   3 +-
 .../rest-api-spec/api/ml.put_job.json         |   3 +-
 .../api/ml.put_trained_model.json             |   5 +-
 .../api/ml.revert_model_snapshot.json         |   3 +-
 .../api/ml.set_upgrade_mode.json              |   3 +-
 .../api/ml.start_data_frame_analytics.json    |   3 +-
 .../rest-api-spec/api/ml.start_datafeed.json  |   3 +-
 .../api/ml.stop_data_frame_analytics.json     |   3 +-
 .../rest-api-spec/api/ml.stop_datafeed.json   |   3 +-
 .../rest-api-spec/api/ml.update_datafeed.json |   5 +-
 .../rest-api-spec/api/ml.update_filter.json   |   3 +-
 .../rest-api-spec/api/ml.update_job.json      |   3 +-
 .../api/ml.update_model_snapshot.json         |   3 +-
 .../rest-api-spec/api/ml.validate.json        |   3 +-
 .../api/ml.validate_detector.json             |   3 +-
 .../rest-api-spec/api/monitoring.bulk.json    |   3 +-
 .../rest-api-spec/api/rollup.delete_job.json  |   3 +-
 .../rest-api-spec/api/rollup.get_jobs.json    |   3 +-
 .../api/rollup.get_rollup_caps.json           |   3 +-
 .../api/rollup.get_rollup_index_caps.json     |   3 +-
 .../rest-api-spec/api/rollup.put_job.json     |   3 +-
 .../api/rollup.rollup_search.json             |   7 +-
 .../rest-api-spec/api/rollup.start_job.json   |   3 +-
 .../rest-api-spec/api/rollup.stop_job.json    |   3 +-
 .../api/security.authenticate.json            |   3 +-
 .../api/security.change_password.json         |   3 +-
 .../api/security.clear_cached_realms.json     |   3 +-
 .../api/security.clear_cached_roles.json      |   3 +-
 .../api/security.create_api_key.json          |   3 +-
 .../api/security.delete_privileges.json       |   3 +-
 .../api/security.delete_role.json             |   3 +-
 .../api/security.delete_role_mapping.json     |   3 +-
 .../api/security.delete_user.json             |   3 +-
 .../api/security.disable_user.json            |   3 +-
 .../api/security.enable_user.json             |   3 +-
 .../api/security.get_api_key.json             |   7 +-
 .../api/security.get_builtin_privileges.json  |   3 +-
 .../api/security.get_privileges.json          |   3 +-
 .../rest-api-spec/api/security.get_role.json  |   3 +-
 .../api/security.get_role_mapping.json        |   3 +-
 .../rest-api-spec/api/security.get_token.json |   3 +-
 .../rest-api-spec/api/security.get_user.json  |   3 +-
 .../api/security.get_user_privileges.json     |   3 +-
 .../api/security.has_privileges.json          |   3 +-
 .../api/security.invalidate_api_key.json      |   3 +-
 .../api/security.invalidate_token.json        |   3 +-
 .../api/security.put_privileges.json          |   3 +-
 .../rest-api-spec/api/security.put_role.json  |   3 +-
 .../api/security.put_role_mapping.json        |   3 +-
 .../rest-api-spec/api/security.put_user.json  |   3 +-
 .../api/slm.delete_lifecycle.json             |   3 +-
 .../api/slm.execute_lifecycle.json            |   3 +-
 .../api/slm.execute_retention.json            |   3 +-
 .../rest-api-spec/api/slm.get_lifecycle.json  |   3 +-
 .../rest-api-spec/api/slm.get_stats.json      |   3 +-
 .../rest-api-spec/api/slm.get_status.json     |   3 +-
 .../rest-api-spec/api/slm.put_lifecycle.json  |   3 +-
 .../rest-api-spec/api/slm.start.json          |   3 +-
 .../resources/rest-api-spec/api/slm.stop.json |   3 +-
 .../rest-api-spec/api/sql.query.json          |   2 +-
 .../rest-api-spec/api/ssl.certificates.json   |   3 +-
 .../api/transform.delete_transform.json       |   3 +-
 .../api/transform.get_transform.json          |   3 +-
 .../api/transform.get_transform_stats.json    |   3 +-
 .../api/transform.preview_transform.json      |   3 +-
 .../api/transform.put_transform.json          |  13 +-
 .../api/transform.start_transform.json        |   3 +-
 .../api/transform.stop_transform.json         |  45 ++--
 .../api/transform.update_transform.json       |  45 ++--
 .../rest-api-spec/api/watcher.ack_watch.json  |   3 +-
 .../api/watcher.activate_watch.json           |   3 +-
 .../api/watcher.deactivate_watch.json         |   3 +-
 .../api/watcher.delete_watch.json             |   3 +-
 .../api/watcher.execute_watch.json            |   3 +-
 .../rest-api-spec/api/watcher.get_watch.json  |   3 +-
 .../rest-api-spec/api/watcher.put_watch.json  |   3 +-
 .../rest-api-spec/api/watcher.start.json      |   3 +-
 .../rest-api-spec/api/watcher.stats.json      |   3 +-
 .../rest-api-spec/api/watcher.stop.json       |   3 +-
 .../rest-api-spec/api/xpack.info.json         |   3 +-
 .../rest-api-spec/api/xpack.usage.json        |   3 +-
 195 files changed, 779 insertions(+), 345 deletions(-)
 create mode 100644 rest-api-spec/src/main/resources/schema.json

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json
index 6ee594b099c4..1ba12b00c817 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json
@@ -63,7 +63,7 @@
           "none",
           "all"
         ],
-        "default": ["all"],
+        "default": "all",
         "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
       }
     }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
index 7e79b7cc2c97..bd7454b8046b 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json
@@ -37,13 +37,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "ts":{
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
index d4a7eb3b051d..a92189134f88 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json
@@ -68,7 +68,6 @@
           "yellow",
           "red"
         ],
-        "default":null,
         "description":"A health status (\"green\", \"yellow\", or \"red\" to filter only indices matching the specified health status"
       },
       "help":{
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json b/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json
index 2a21ff3725b6..894b141f2f3b 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json
@@ -97,7 +97,6 @@
           "yellow",
           "red"
         ],
-        "default":null,
         "description":"Wait until cluster is in a specific state"
       }
     }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json b/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
index 9be09b49cc54..8641c18382df 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
@@ -56,7 +56,6 @@
         "description":"Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
       },
       "conflicts":{
-        "note":"This is not copied from search",
         "type":"enum",
         "options":[
           "abort",
@@ -160,7 +159,7 @@
       },
       "scroll_size":{
         "type":"number",
-        "defaut_value":100,
+        "default":100,
         "description":"Size on the scroll request powering the delete by query"
       },
       "wait_for_completion":{
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json b/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json
index 16e8d0a0cfab..aa770ee9d9f2 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_context.json
@@ -1,6 +1,7 @@
 {
   "get_script_context":{
     "documentation":{
+      "url": "https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html",
       "description":"Returns all script contexts."
     },
     "stability":"experimental",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json b/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json
index 5a45392d9ee1..a5e06cb88901 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/get_script_languages.json
@@ -1,6 +1,7 @@
 {
   "get_script_languages":{
     "documentation":{
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
       "description":"Returns available script types, languages and contexts"
     },
     "stability":"experimental",
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json
index e238c4fc38af..5bfdd985a0a8 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json
@@ -73,7 +73,7 @@
           "none",
           "all"
         ],
-        "default": ["all"],
+        "default": "all",
         "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
       },
       "local":{
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json
index 4a1dea974f75..68e325446d3d 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json
@@ -77,10 +77,7 @@
           "none",
           "all"
         ],
-        "default":[
-          "open",
-          "closed"
-        ],
+        "default": "all",
         "description":"Whether to expand wildcard expression to concrete indices that are open, closed or both."
       },
       "flat_settings":{
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json b/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json
index 1d216dcb0b32..ca4783368d1b 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json
@@ -30,7 +30,6 @@
         "type" : "time",
         "description" : "Explicit operation timeout"
       }
-    },
-    "body": {}
+    }
   }
 }
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json b/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json
index 299c4f705d29..86fa8a60db43 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json
@@ -56,7 +56,6 @@
         "description":"Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
       },
       "conflicts":{
-        "note":"This is not copied from search",
         "type":"enum",
         "options":[
           "abort",
@@ -168,7 +167,7 @@
       },
       "scroll_size":{
         "type":"number",
-        "defaut_value":100,
+        "default":100,
         "description":"Size on the scroll request powering the update by query"
       },
       "wait_for_completion":{
diff --git a/rest-api-spec/src/main/resources/schema.json b/rest-api-spec/src/main/resources/schema.json
new file mode 100644
index 000000000000..0e7b84fb39bf
--- /dev/null
+++ b/rest-api-spec/src/main/resources/schema.json
@@ -0,0 +1,245 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://github.com/elastic/elasticsearch/tree/master/rest-api-spec",
+    "$ref": "#/definitions/Api",
+    "definitions": {
+        "Api": {
+            "type": "object",
+            "propertyNames": {
+                "pattern": "^[a-z]+?(_[a-z]+)*(\\.[a-z]+?(_[a-z]+)*)?$"
+            },
+            "minProperties": 1,
+            "maxProperties": 1,
+            "patternProperties": {
+                "^[a-z]+?(_[a-z]+)*(\\.[a-z]+?(_[a-z]+)*)?$": {
+                    "$ref": "#/definitions/Components"
+                }
+            },
+            "additionalProperties": false,
+            "title": "API name",
+            "description": "An object with a single property name of the API and value of the API components"
+        },
+        "Components": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "deprecated": {
+                    "$ref": "#/definitions/Deprecated"
+                },
+                "documentation": {
+                    "$ref": "#/definitions/Documentation"
+                },
+                "stability": {
+                    "type": "string",
+                    "enum": ["stable", "beta", "experimental", "private"]
+                },
+                "url": {
+                    "$ref": "#/definitions/Url"
+                },
+                "params": {
+                    "$ref": "#/definitions/Params"
+                },
+                "body": {
+                    "$ref": "#/definitions/Body"
+                }
+            },
+            "required": [
+                "documentation",
+                "stability",
+                "url"
+            ],
+            "title": "API components",
+            "description": "The components that make up the API"
+        },
+        "Url": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "paths": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/Path"
+                    },
+                    "minLength": 1
+                }
+            },
+            "required": [
+                "paths"
+            ],
+            "title": "API urls",
+            "description": "An array of the URL path variants for the API"
+        },
+        "Params": {
+            "type": "object",
+            "additionalProperties": true,
+            "propertyNames": {
+              "pattern": "^_?[a-z]+?(_[a-z]+)*$"
+            },
+            "patternProperties": {
+                "^_?[a-z]+?(_[a-z]+)*$": {
+                    "$ref": "#/definitions/ParamPart"
+                }
+            },
+            "title": "API query string parameters",
+            "description": "A collection of the query string parameters for the API"
+        },
+        "Body": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "description": {
+                    "type": "string"
+                },
+                "required": {
+                    "type": "boolean"
+                },
+                "serialize": {
+                    "type": "string",
+                    "enum": ["bulk"]
+                }
+            },
+            "required": [
+                "description"
+            ],
+            "title": "API request Body",
+            "description": "The request body for the API. Does not detail the structure, only whether the API accepts a body and its format"
+        },
+        "Deprecated": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "version": {
+                    "type": "string",
+                    "pattern": "^\\d+\\.\\d+\\.\\d+$",
+                    "title": "The version from which deprecation applies"
+                },
+                "description": {
+                    "type": "string",
+                    "title": "A description for the deprecation, which may include alternatives to use"
+                }
+            },
+            "required": [
+                "description",
+                "version"
+            ],
+            "title": "Deprecation",
+            "description": "Indicates if part of the API is deprecated, in what version and why"
+        },
+        "Documentation": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "format": "uri"
+                },
+                "description": {
+                    "type": "string"
+                }
+            },
+            "required": [
+                "url",
+                "description"
+            ],
+            "title": "Documentation",
+            "description": "API documentation including a link to the public reference and a short descritpion"
+        },
+        "Parts": {
+            "type": "object",
+            "additionalProperties": true,
+            "propertyNames": {
+              "pattern": "^_?[a-z]+?(_[a-z]+)*$"
+            },
+            "patternProperties": {
+                "^_?[a-z]+?(_[a-z]+)*$": {
+                    "$ref": "#/definitions/ParamPart"
+                }
+            },
+            "title": "API url parts",
+            "description": "Variable parts that make up an API url path"
+        },
+        "ParamPart": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "pattern": "^list|date|time|string|enum|int|double|long|boolean|number$",
+                    "title": "The type of the parameter."
+                },
+                "options": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_]+$"
+                    },
+                    "title": "Valid options when type is an enum"
+                },
+                "default": {
+                    "type": ["string", "number", "boolean"],
+                    "title": "Default value"
+                },
+                "deprecated": {
+                    "oneOf": [
+                      { "$ref": "#/definitions/Deprecated" },
+                      { "type": "boolean" }
+                    ]
+                },
+                "description": {
+                    "type": "string",
+                    "title": "A description for the parameter"
+                },
+                "required": {
+                    "type": "boolean",
+                    "title": "Whether the parameter is required"
+                }
+            },
+            "required": [
+                "description",
+                "type"
+            ],
+            "allOf": [
+                {
+                    "if": {
+                        "properties": { "type": { "const": "enum" } }
+                    },
+                    "then": {
+                        "required": ["options"]
+                    }
+                }
+            ],
+            "title": "API parameter or part",
+            "description": "The properties of an API parameter or part"
+        },
+        "Path": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "pattern": "^\\/([a-z0-9\\/_{}])*$"
+                },
+                "methods": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "enum": ["DELETE", "GET", "HEAD", "POST", "PUT"],
+                        "minLength": 1
+                    }
+                },
+                "parts": {
+                    "$ref": "#/definitions/Parts"
+                },
+                "deprecated": {
+                    "$ref": "#/definitions/Deprecated"
+                }
+            },
+            "required": [
+                "methods",
+                "path"
+            ],
+            "title": "API path",
+            "description": "A path variant for the API including the HTTP methods it supports and parts"
+        }
+    }
+}
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.delete.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.delete.json
index 10416b04ce5c..70794f4a8b76 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.delete.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.delete.json
@@ -1,7 +1,8 @@
 {
   "async_search.delete":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html",
+      "description": "Deletes an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.get.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.get.json
index 4207ebba0a46..76c4650ab079 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.get.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.get.json
@@ -1,7 +1,8 @@
 {
   "async_search.get":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html",
+      "description": "Retrieves the results of a previously submitted async search request given its ID."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.submit.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.submit.json
index c45c31c134da..1f4d0b9a6bf3 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.submit.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/async_search.submit.json
@@ -1,7 +1,8 @@
 {
   "async_search.submit":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html",
+      "description": "Executes a search request asynchronously."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/autoscaling.get_autoscaling_decision.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/autoscaling.get_autoscaling_decision.json
index e6ecd75312d5..26ce055aad35 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/autoscaling.get_autoscaling_decision.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/autoscaling.get_autoscaling_decision.json
@@ -1,7 +1,8 @@
 {
   "autoscaling.get_autoscaling_decision":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-get-autoscaling-decision.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/autoscaling-get-autoscaling-decision.html",
+      "description": "Gets the current autoscaling decision based on the configured autoscaling policy, indicating whether or not autoscaling is needed."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json
index 072ba74f6f8e..ec041788fffc 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "cat.ml_data_frame_analytics":{
     "documentation":{
-      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-dfanalytics.html"
+      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-dfanalytics.html",
+      "description": "Gets configuration and usage information about data frame analytics jobs."
     },
     "stability":"stable",
     "url":{
@@ -70,13 +71,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "v":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json
index d750ff56b897..c7f4cce0cd57 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json
@@ -1,7 +1,8 @@
 {
   "cat.ml_datafeeds":{
     "documentation":{
-      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-datafeeds.html"
+      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-datafeeds.html",
+      "description": "Gets configuration and usage information about datafeeds."
     },
     "stability":"stable",
     "url":{
@@ -53,13 +54,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "v":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_jobs.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_jobs.json
index f62a46ba3413..53187760d5cd 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_jobs.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_jobs.json
@@ -1,7 +1,8 @@
 {
   "cat.ml_jobs":{
     "documentation":{
-      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-anomaly-detectors.html"
+      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-anomaly-detectors.html",
+      "description": "Gets configuration and usage information about anomaly detection jobs."
     },
     "stability":"stable",
     "url":{
@@ -70,13 +71,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "v":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
index 77875d03a2f7..e129d3201abe 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
@@ -1,7 +1,8 @@
 {
   "cat.ml_trained_models":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-trained-model.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-trained-model.html",
+      "description": "Gets configuration and usage information about inference trained models."
     },
     "stability":"stable",
     "url":{
@@ -81,13 +82,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "v":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.transform.json
index 98a2fcac1c28..66b55d9a4bbc 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.transform.json
@@ -1,7 +1,8 @@
 {
   "cat.transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-transforms.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-transforms.html",
+      "description": "Gets configuration and usage information about transforms."
     },
     "stability":"stable",
     "url":{
@@ -63,13 +64,13 @@
         "type":"enum",
         "description":"The unit in which to display time values",
         "options":[
-          "d (Days)",
-          "h (Hours)",
-          "m (Minutes)",
-          "s (Seconds)",
-          "ms (Milliseconds)",
-          "micros (Microseconds)",
-          "nanos (Nanoseconds)"
+          "d",
+          "h",
+          "m",
+          "s",
+          "ms",
+          "micros",
+          "nanos"
         ]
       },
       "v":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.delete_auto_follow_pattern.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.delete_auto_follow_pattern.json
index 411bc10db946..f9e70a1f6ac9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.delete_auto_follow_pattern.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.delete_auto_follow_pattern.json
@@ -1,7 +1,8 @@
 {
   "ccr.delete_auto_follow_pattern":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-delete-auto-follow-pattern.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-delete-auto-follow-pattern.html",
+      "description": "Deletes auto-follow patterns."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow.json
index 830c3d7e02cb..be3dfc752175 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow.json
@@ -1,7 +1,8 @@
 {
   "ccr.follow":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-follow.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-follow.html",
+      "description": "Creates a new follower index configured to follow the referenced leader index."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_info.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_info.json
index dbe5f53f2478..858eab0b9180 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_info.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_info.json
@@ -1,7 +1,8 @@
 {
   "ccr.follow_info":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-info.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-info.html",
+      "description": "Retrieves information about all follower indices, including parameters and status for each follower index"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_stats.json
index aecfd50a6a90..1abe53bd21c2 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.follow_stats.json
@@ -1,7 +1,8 @@
 {
   "ccr.follow_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-follow-stats.html",
+      "description": "Retrieves follower stats. return shard-level stats about the following tasks associated with each shard for the specified indices."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.forget_follower.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.forget_follower.json
index 4d4af1a60725..d0df2f164feb 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.forget_follower.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.forget_follower.json
@@ -1,7 +1,8 @@
 {
   "ccr.forget_follower":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-forget-follower.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-forget-follower.html",
+      "description": "Removes the follower retention leases from the leader."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.get_auto_follow_pattern.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.get_auto_follow_pattern.json
index 8d34c1e59711..b89587d2611f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.get_auto_follow_pattern.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.get_auto_follow_pattern.json
@@ -1,7 +1,8 @@
 {
   "ccr.get_auto_follow_pattern":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-auto-follow-pattern.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-auto-follow-pattern.html",
+      "description": "Gets configured auto-follow patterns. Returns the specified auto-follow pattern collection."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_auto_follow_pattern.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_auto_follow_pattern.json
index 9e76b83bb904..711e3deb3193 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_auto_follow_pattern.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_auto_follow_pattern.json
@@ -1,7 +1,8 @@
 {
   "ccr.pause_auto_follow_pattern":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-pause-auto-follow-pattern.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-pause-auto-follow-pattern.html",
+      "description": "Pauses an auto-follow pattern"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_follow.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_follow.json
index 54b457657598..f45947b1a872 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_follow.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.pause_follow.json
@@ -1,7 +1,8 @@
 {
   "ccr.pause_follow":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-pause-follow.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-pause-follow.html",
+      "description": "Pauses a follower index. The follower index will not fetch any additional operations from the leader index."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.put_auto_follow_pattern.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.put_auto_follow_pattern.json
index 7edcb6290315..79a498da16dc 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.put_auto_follow_pattern.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.put_auto_follow_pattern.json
@@ -1,7 +1,8 @@
 {
   "ccr.put_auto_follow_pattern":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-auto-follow-pattern.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-put-auto-follow-pattern.html",
+      "description": "Creates a new named collection of auto-follow patterns against a specified remote cluster. Newly created indices on the remote cluster matching any of the specified patterns will be automatically configured as follower indices."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_auto_follow_pattern.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_auto_follow_pattern.json
index 96b77cb82e93..e6c3d268b164 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_auto_follow_pattern.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_auto_follow_pattern.json
@@ -1,7 +1,8 @@
 {
   "ccr.resume_auto_follow_pattern":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-resume-auto-follow-pattern.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-resume-auto-follow-pattern.html",
+      "description": "Resumes an auto-follow pattern that has been paused"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_follow.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_follow.json
index c6b3135fd7f3..de1945f347b6 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_follow.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.resume_follow.json
@@ -1,7 +1,8 @@
 {
   "ccr.resume_follow":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-resume-follow.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-resume-follow.html",
+      "description": "Resumes a follower index that has been paused"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.stats.json
index fcf36bf188ae..dc70f1a3971d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.stats.json
@@ -1,7 +1,8 @@
 {
   "ccr.stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-get-stats.html",
+      "description": "Gets all stats related to cross-cluster replication."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.unfollow.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.unfollow.json
index 1730a728c5e3..c5db9219a395 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.unfollow.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ccr.unfollow.json
@@ -1,7 +1,8 @@
 {
   "ccr.unfollow":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-unfollow.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-post-unfollow.html",
+      "description": "Stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.delete_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.delete_transform.json
index 2949ceb44499..28c90b604f68 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.delete_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.delete_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.delete_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-transform.html",
+      "description":"Deletes an existing transform."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform.json
index 466e687bd19e..17f333861c5d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.get_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform.html",
+      "description":"Retrieves configuration information for transforms."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform_stats.json
index eb5dd8d5d2f6..7822f3ce5c04 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.get_transform_stats.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.get_transform_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform-stats.html",
+      "description":"Retrieves usage information for transforms."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.preview_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.preview_transform.json
index 1ae012d28cbe..90b9b9173aaa 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.preview_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.preview_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.preview_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/preview-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/preview-transform.html",
+      "description":"Previews a transform."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.put_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.put_transform.json
index 27256eb782f6..ce86e733ba51 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.put_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.put_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.put_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-transform.html",
+      "description":"Instantiates a transform."
     },
     "stability":"beta",
     "url":{
@@ -24,11 +25,11 @@
         }
       ]
     },
-    "params": {
-      "defer_validation": {
-        "type": "boolean",
-        "required": false,
-        "description": "If validations should be deferred until transform starts, defaults to false."
+    "params":{
+      "defer_validation":{
+        "type":"boolean",
+        "required":false,
+        "description":"If validations should be deferred until transform starts, defaults to false."
       }
     },
     "body":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.start_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.start_transform.json
index f47bd61726e8..fd9e25619d76 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.start_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.start_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.start_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-transform.html",
+      "description":"Starts one or more transforms."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.stop_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.stop_transform.json
index 434375a9fabd..8938ec5bc8e1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.stop_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.stop_transform.json
@@ -1,7 +1,8 @@
 {
   "data_frame_transform_deprecated.stop_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-transform.html",
+      "description":"Stops one or more transforms."
     },
     "stability":"beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.update_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.update_transform.json
index d1c0bb2456a7..97e1821b53c2 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.update_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/data_frame_transform_deprecated.update_transform.json
@@ -1,19 +1,22 @@
 {
-  "data_frame_transform_deprecated.update_transform": {
-    "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/update-transform.html"
+  "data_frame_transform_deprecated.update_transform":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/update-transform.html",
+      "description":"Updates certain properties of a transform."
     },
-    "stability": "beta",
-    "url": {
-      "paths": [
+    "stability":"beta",
+    "url":{
+      "paths":[
         {
-          "path": "/_data_frame/transforms/{transform_id}/_update",
-          "methods": [ "POST" ],
-          "parts": {
-            "transform_id": {
-              "type": "string",
-              "required": true,
-              "description": "The id of the transform."
+          "path":"/_data_frame/transforms/{transform_id}/_update",
+          "methods":[
+            "POST"
+          ],
+          "parts":{
+            "transform_id":{
+              "type":"string",
+              "required":true,
+              "description":"The id of the transform."
             }
           },
           "deprecated":{
@@ -23,16 +26,16 @@
         }
       ]
     },
-    "params": {
-      "defer_validation": {
-        "type": "boolean",
-        "required": false,
-        "description": "If validations should be deferred until transform starts, defaults to false."
+    "params":{
+      "defer_validation":{
+        "type":"boolean",
+        "required":false,
+        "description":"If validations should be deferred until transform starts, defaults to false."
       }
     },
-    "body": {
-      "description" : "The update transform definition",
-      "required": true
+    "body":{
+      "description":"The update transform definition",
+      "required":true
     }
   }
 }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.delete_policy.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.delete_policy.json
index 2d4fd1a7baf2..f7a183025108 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.delete_policy.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.delete_policy.json
@@ -1,7 +1,8 @@
 {
   "enrich.delete_policy": {
     "documentation": {
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-enrich-policy-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-enrich-policy-api.html",
+      "description": "Deletes an existing enrich policy and its enrich index."
     },
     "stability" : "stable",
     "url": {
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.execute_policy.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.execute_policy.json
index 90413423a9dc..a448d91062cc 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.execute_policy.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.execute_policy.json
@@ -1,7 +1,8 @@
 {
   "enrich.execute_policy": {
     "documentation": {
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/execute-enrich-policy-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/execute-enrich-policy-api.html",
+      "description": "Creates the enrich index for an existing enrich policy."
     },
     "stability" : "stable",
     "url": {
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.get_policy.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.get_policy.json
index ab0d699dbf9f..32bdf01f3400 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.get_policy.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.get_policy.json
@@ -1,7 +1,8 @@
 {
   "enrich.get_policy": {
     "documentation": {
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-enrich-policy-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-enrich-policy-api.html",
+      "description": "Gets information about an enrich policy."
     },
     "stability" : "stable",
     "url": {
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.put_policy.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.put_policy.json
index c23bec02ab0a..107871584436 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.put_policy.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.put_policy.json
@@ -1,7 +1,8 @@
 {
   "enrich.put_policy": {
     "documentation": {
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-enrich-policy-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-enrich-policy-api.html",
+      "description": "Creates a new enrich policy."
     },
     "stability" : "stable",
     "url": {
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.stats.json
index 69175d556347..153ee42b7a7b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/enrich.stats.json
@@ -1,7 +1,8 @@
 {
   "enrich.stats": {
     "documentation": {
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/enrich-stats-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/enrich-stats-api.html",
+      "description": "Gets enrich coordinator statistics and information about enrich policies that are currently executing."
     },
     "stability" : "stable",
     "url": {
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/eql.search.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/eql.search.json
index 68c105a41d7e..4e56583722bb 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/eql.search.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/eql.search.json
@@ -1,7 +1,8 @@
 {
   "eql.search":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html",
+      "description": "Returns results matching a query expressed in Event Query Language (EQL)"
     },
     "stability": "beta",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/graph.explore.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/graph.explore.json
index 253ab219d528..575ba9c690c9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/graph.explore.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/graph.explore.json
@@ -1,7 +1,8 @@
 {
   "graph.explore":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/graph-explore-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/graph-explore-api.html",
+      "description": "Explore extracted and summarized information about the documents and terms in an index."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.delete_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.delete_lifecycle.json
index 50c15a9b6ee1..59c14b3c9e2b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.delete_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.delete_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "ilm.delete_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-delete-lifecycle.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-delete-lifecycle.html",
+      "description": "Deletes the specified lifecycle policy definition. A currently used policy cannot be deleted."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.explain_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.explain_lifecycle.json
index e00cc9aceb9e..9a8f11ae5bc0 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.explain_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.explain_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "ilm.explain_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-explain-lifecycle.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-explain-lifecycle.html",
+      "description": "Retrieves information about the index's current lifecycle state, such as the currently executing phase, action, and step."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_lifecycle.json
index 231748795613..6846d92b97e0 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "ilm.get_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-lifecycle.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-lifecycle.html",
+      "description": "Returns the specified policy definition. Includes the policy version and last modified date."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_status.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_status.json
index 0e94c2259696..1808e903a68f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_status.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.get_status.json
@@ -1,7 +1,8 @@
 {
   "ilm.get_status":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-status.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-get-status.html",
+      "description":"Retrieves the current index lifecycle management (ILM) status."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.move_to_step.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.move_to_step.json
index 1f46cd2e0053..c3b397ba8a8e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.move_to_step.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.move_to_step.json
@@ -1,7 +1,8 @@
 {
   "ilm.move_to_step":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-move-to-step.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-move-to-step.html",
+      "description":"Manually moves an index into the specified step and executes that step."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.put_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.put_lifecycle.json
index b33521cf5127..260292118a7b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.put_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.put_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "ilm.put_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-put-lifecycle.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-put-lifecycle.html",
+      "description":"Creates a lifecycle policy"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.remove_policy.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.remove_policy.json
index f2b843017e67..e39c95f68d7e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.remove_policy.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.remove_policy.json
@@ -1,7 +1,8 @@
 {
   "ilm.remove_policy":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-remove-policy.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-remove-policy.html",
+      "description":"Removes the assigned lifecycle policy and stops managing the specified index"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.retry.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.retry.json
index c25a84521405..ab957713db01 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.retry.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.retry.json
@@ -1,7 +1,8 @@
 {
   "ilm.retry":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-retry-policy.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-retry-policy.html",
+      "description":"Retries executing the policy for an index that is in the ERROR step."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.start.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.start.json
index f6dd48beac5c..56ca5a4ad4c4 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.start.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.start.json
@@ -1,7 +1,8 @@
 {
   "ilm.start":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-start.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-start.html",
+      "description":"Start the index lifecycle management (ILM) plugin."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.stop.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.stop.json
index c49bbf327db3..9604499cecaf 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.stop.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ilm.stop.json
@@ -1,7 +1,8 @@
 {
   "ilm.stop":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-stop.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ilm-stop.html",
+      "description":"Halts all lifecycle management operations and stops the index lifecycle management (ILM) plugin"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.freeze.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.freeze.json
index 28a051012fa1..2966db1d015b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.freeze.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.freeze.json
@@ -1,7 +1,8 @@
 {
   "indices.freeze":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/frozen.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/freeze-index-api.html",
+      "description":"Freezes an index. A frozen index has almost no overhead on the cluster (except for maintaining its metadata in memory) and is read-only."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.reload_search_analyzers.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.reload_search_analyzers.json
index 75d871a5145d..2c0214976b30 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.reload_search_analyzers.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.reload_search_analyzers.json
@@ -1,7 +1,8 @@
 {
   "indices.reload_search_analyzers":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-reload-analyzers.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-reload-analyzers.html",
+      "description":"Reloads an index's search analyzers and their resources."
     },
     "stability" : "stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.unfreeze.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.unfreeze.json
index 651a79d0c42a..bc527f6f1958 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.unfreeze.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/indices.unfreeze.json
@@ -1,7 +1,8 @@
 {
   "indices.unfreeze":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/frozen.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/unfreeze-index-api.html",
+      "description":"Unfreezes an index. When a frozen index is unfrozen, the index goes through the normal recovery process and becomes writeable again."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.delete.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.delete.json
index 9c369c384c2f..153f38b264ff 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.delete.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.delete.json
@@ -1,7 +1,8 @@
 {
   "license.delete":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-license.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-license.html",
+      "description":"Deletes licensing information for the cluster"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get.json
index f3fc15845e9b..1820affbcf90 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get.json
@@ -1,7 +1,8 @@
 {
   "license.get":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-license.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-license.html",
+      "description":"Retrieves licensing information for the cluster"
     },
     "stability":"stable",
     "url":{
@@ -21,8 +22,8 @@
       },
       "accept_enterprise":{
         "type":"boolean",
-        "deprecated":true,
-        "description":"Supported for backwards compatibility with 7.x. If this param is used it must be set to true"
+        "description":"Supported for backwards compatibility with 7.x. If this param is used it must be set to true",
+        "deprecated":true
       }
     }
   }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_basic_status.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_basic_status.json
index b3d10f1e1c08..d29bc9ffba6c 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_basic_status.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_basic_status.json
@@ -1,7 +1,8 @@
 {
   "license.get_basic_status":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-basic-status.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-basic-status.html",
+      "description":"Retrieves information about the status of the basic license."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_trial_status.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_trial_status.json
index 072608982da9..71c854b4f5d9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_trial_status.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.get_trial_status.json
@@ -1,7 +1,8 @@
 {
   "license.get_trial_status":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-trial-status.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/get-trial-status.html",
+      "description":"Retrieves information about the status of the trial license."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post.json
index 4b53ebeaa72a..2b637f8577b4 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post.json
@@ -1,7 +1,8 @@
 {
   "license.post":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/update-license.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/update-license.html",
+      "description":"Updates the license for the cluster."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_basic.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_basic.json
index 3aa928ec1503..855a90cfe2a7 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_basic.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_basic.json
@@ -1,7 +1,8 @@
 {
   "license.post_start_basic":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-basic.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-basic.html",
+      "description":"Starts an indefinite basic license."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_trial.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_trial.json
index a28b45dc8dea..ebf5f7188011 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_trial.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/license.post_start_trial.json
@@ -1,7 +1,8 @@
 {
   "license.post_start_trial":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-trial.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-trial.html",
+      "description":"starts a limited time trial license."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/migration.deprecations.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/migration.deprecations.json
index 6be7d2006410..ca19147c0525 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/migration.deprecations.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/migration.deprecations.json
@@ -1,7 +1,8 @@
 {
   "migration.deprecations":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-deprecation.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-deprecation.html",
+      "description":"Retrieves information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.close_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.close_job.json
index 7627a08a6ac6..f51ebf62b895 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.close_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.close_job.json
@@ -1,7 +1,8 @@
 {
   "ml.close_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-close-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-close-job.html",
+      "description":"Closes one or more anomaly detection jobs. A job can be opened and closed multiple times throughout its lifecycle."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar.json
index 4614965a098c..7cf3501b2655 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_calendar":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-calendar.html",
+      "description":"Deletes a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_event.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_event.json
index a6b70a142788..aa6e2d310a5f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_event.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_event.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_calendar_event":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-calendar-event.html",
+      "description":"Deletes scheduled events from a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_job.json
index 5d88f42b7641..075ddcac10f5 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_calendar_job.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_calendar_job":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-calendar-job.html",
+      "description":"Deletes anomaly detection jobs from a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_data_frame_analytics.json
index c85cf60651a2..4a077b375e77 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_data_frame_analytics":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-dfanalytics.html",
+      "description":"Deletes an existing data frame analytics job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_datafeed.json
index 9df83f1b8257..d3abeaa6c120 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-datafeed.html",
+      "description":"Deletes an existing datafeed."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_expired_data.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_expired_data.json
index 598cad6b0bc3..ac38a7a34493 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_expired_data.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_expired_data.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_expired_data":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-expired-data.html",
+      "description":"Deletes expired and unused machine learning data."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_filter.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_filter.json
index bcb0fe310b9a..9556a0fe472b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_filter.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_filter.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_filter":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-filter.html",
+      "description":"Deletes a filter."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_forecast.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_forecast.json
index c53dd95e8155..08f4a79e0f86 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_forecast.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_forecast.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_forecast":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-forecast.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-forecast.html",
+      "description":"Deletes forecasts from a machine learning job."
     },
     "stability":"stable",
     "url":{
@@ -44,7 +45,7 @@
       },
       "timeout":{
         "type":"time",
-        "requred":false,
+        "required":false,
         "description":"Controls the time to wait until the forecast(s) are deleted. Default to 30 seconds"
       }
     }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_job.json
index bdcea04d16ff..eb820441fddf 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_job.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-job.html",
+      "description":"Deletes an existing anomaly detection job."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_model_snapshot.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_model_snapshot.json
index b5735da3cc12..b6caa438acd1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_model_snapshot.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_model_snapshot.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_model_snapshot":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-snapshot.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-delete-snapshot.html",
+      "description":"Deletes an existing model snapshot."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_trained_model.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_trained_model.json
index 01e935bd4ad5..27d24cd77594 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_trained_model.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.delete_trained_model.json
@@ -1,7 +1,8 @@
 {
   "ml.delete_trained_model":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-inference.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-inference.html",
+      "description":"Deletes an existing trained inference model that is currently not referenced by an ingest pipeline."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.estimate_model_memory.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.estimate_model_memory.json
index 6eaa707a4969..4a024f937225 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.estimate_model_memory.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.estimate_model_memory.json
@@ -1,7 +1,8 @@
 {
   "ml.estimate_model_memory":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-apis.html",
+      "description":"Estimates the model memory"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.evaluate_data_frame.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.evaluate_data_frame.json
index 6d7770fcd4f4..9190f52adba8 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.evaluate_data_frame.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.evaluate_data_frame.json
@@ -1,7 +1,8 @@
 {
   "ml.evaluate_data_frame":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/evaluate-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/evaluate-dfanalytics.html",
+      "description":"Evaluates the data frame analytics for an annotated index."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.explain_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.explain_data_frame_analytics.json
index 6969cf9a49f1..9210862db960 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.explain_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.explain_data_frame_analytics.json
@@ -1,19 +1,26 @@
 {
-  "ml.explain_data_frame_analytics": {
-    "documentation": {
-      "url": "http://www.elastic.co/guide/en/elasticsearch/reference/current/explain-dfanalytics.html"
+  "ml.explain_data_frame_analytics":{
+    "documentation":{
+      "url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/explain-dfanalytics.html",
+      "description":"Explains a data frame analytics config."
     },
-    "stability": "experimental",
-    "url": {
-      "paths" : [
+    "stability":"experimental",
+    "url":{
+      "paths":[
         {
-          "path" : "/_ml/data_frame/analytics/_explain",
-          "methods": [ "GET", "POST" ],
-          "parts": {}
+          "path":"/_ml/data_frame/analytics/_explain",
+          "methods":[
+            "GET",
+            "POST"
+          ],
+          "parts":{}
         },
         {
-          "path" : "/_ml/data_frame/analytics/{id}/_explain",
-          "methods": [ "GET", "POST" ],
+          "path":"/_ml/data_frame/analytics/{id}/_explain",
+          "methods":[
+            "GET",
+            "POST"
+          ],
           "parts":{
             "id":{
               "type":"string",
@@ -23,9 +30,9 @@
         }
       ]
     },
-    "body": {
-      "description" : "The data frame analytics config to explain",
-      "required" : false
+    "body":{
+      "description":"The data frame analytics config to explain",
+      "required":false
     }
   }
 }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.find_file_structure.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.find_file_structure.json
index 46b4f5afb051..13594031fc60 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.find_file_structure.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.find_file_structure.json
@@ -1,7 +1,8 @@
 {
   "ml.find_file_structure":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-find-file-structure.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-find-file-structure.html",
+      "description":"Finds the structure of a text file. The text file must contain data that is suitable to be ingested into Elasticsearch."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.flush_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.flush_job.json
index 695935f9fb86..3e2f7f365bab 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.flush_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.flush_job.json
@@ -1,7 +1,8 @@
 {
   "ml.flush_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-flush-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-flush-job.html",
+      "description":"Forces any buffered data to be processed by the job."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.forecast.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.forecast.json
index 71475feb6f92..fa5c1ffe7c8c 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.forecast.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.forecast.json
@@ -1,7 +1,8 @@
 {
   "ml.forecast":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-forecast.html",
+      "description":"Predicts the future behavior of a time series by using its historical behavior."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_buckets.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_buckets.json
index 1be237653624..90f7cedea540 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_buckets.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_buckets.json
@@ -1,7 +1,8 @@
 {
   "ml.get_buckets":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-bucket.html",
+      "description":"Retrieves anomaly detection job results for one or more buckets."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendar_events.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendar_events.json
index f0f57b05ef1f..0bb10780d1df 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendar_events.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendar_events.json
@@ -1,7 +1,8 @@
 {
   "ml.get_calendar_events":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-calendar-event.html",
+      "description":"Retrieves information about the scheduled events in calendars."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendars.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendars.json
index d863f8338752..ec6268acb49e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendars.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendars.json
@@ -1,7 +1,8 @@
 {
   "ml.get_calendars":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-calendar.html",
+      "description":"Retrieves configuration information for calendars."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_categories.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_categories.json
index c089cf87b5e3..973382de630a 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_categories.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_categories.json
@@ -1,7 +1,8 @@
 {
   "ml.get_categories":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-category.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-category.html",
+      "description":"Retrieves anomaly detection job results for one or more categories."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics.json
index 82567d75426c..80b4649453f7 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "ml.get_data_frame_analytics":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-dfanalytics.html",
+      "description":"Retrieves configuration information for data frame analytics jobs."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics_stats.json
index 5390aab47c97..1c35de865e02 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_data_frame_analytics_stats.json
@@ -1,7 +1,8 @@
 {
   "ml.get_data_frame_analytics_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-dfanalytics-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-dfanalytics-stats.html",
+      "description":"Retrieves usage information for data frame analytics jobs."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeed_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeed_stats.json
index cf390848312f..3c0177f66d1f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeed_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeed_stats.json
@@ -1,7 +1,8 @@
 {
   "ml.get_datafeed_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed-stats.html",
+      "description":"Retrieves usage information for datafeeds."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeeds.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeeds.json
index c17c8eb194fd..e475f216dbc1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeeds.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_datafeeds.json
@@ -1,7 +1,8 @@
 {
   "ml.get_datafeeds":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed.html",
+      "description":"Retrieves configuration information for datafeeds."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_filters.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_filters.json
index 20672c04b900..b56518c524e6 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_filters.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_filters.json
@@ -1,7 +1,8 @@
 {
   "ml.get_filters":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-filter.html",
+      "description":"Retrieves filters."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_influencers.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_influencers.json
index 8730f7b185ec..25f68ab014af 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_influencers.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_influencers.json
@@ -1,7 +1,8 @@
 {
   "ml.get_influencers":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-influencer.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-influencer.html",
+      "description":"Retrieves anomaly detection job results for one or more influencers."
     },
     "stability":"stable",
     "url":{
@@ -14,7 +15,8 @@
           ],
           "parts":{
             "job_id":{
-              "type":"string"
+              "type":"string",
+              "description":"Identifier for the anomaly detection job"
             }
           }
         }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_job_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_job_stats.json
index 8f4f69529079..29df54a46307 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_job_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_job_stats.json
@@ -1,7 +1,8 @@
 {
   "ml.get_job_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job-stats.html",
+      "description":"Retrieves usage information for anomaly detection jobs."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_jobs.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_jobs.json
index fa456d9130d6..58c595276e88 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_jobs.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_jobs.json
@@ -1,7 +1,8 @@
 {
   "ml.get_jobs":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html",
+      "description":"Retrieves configuration information for anomaly detection jobs."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_model_snapshots.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_model_snapshots.json
index 8a2f4885e9fe..5dafaa43d8e3 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_model_snapshots.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_model_snapshots.json
@@ -1,7 +1,8 @@
 {
   "ml.get_model_snapshots":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-snapshot.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-snapshot.html",
+      "description":"Retrieves information about model snapshots."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_overall_buckets.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_overall_buckets.json
index 23239ae748c7..aac547a17832 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_overall_buckets.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_overall_buckets.json
@@ -1,7 +1,8 @@
 {
   "ml.get_overall_buckets":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-overall-buckets.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-overall-buckets.html",
+      "description":"Retrieves overall bucket results that summarize the bucket results of multiple anomaly detection jobs."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_records.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_records.json
index fc87d924c292..9d8658972e6e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_records.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_records.json
@@ -1,7 +1,8 @@
 {
   "ml.get_records":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-record.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-record.html",
+      "description":"Retrieves anomaly records for an anomaly detection job."
     },
     "stability":"stable",
     "url":{
@@ -14,7 +15,8 @@
           ],
           "parts":{
             "job_id":{
-              "type":"string"
+              "type":"string",
+              "description":"The ID of the job"
             }
           }
         }
@@ -42,7 +44,8 @@
         "description":"End time filter for records"
       },
       "record_score":{
-        "type":"double"
+        "type":"double",
+        "description":"Returns records with anomaly scores greater or equal than this value"
       },
       "sort":{
         "type":"string",
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models.json
index 7c41285bd1ca..3b5b42795bda 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models.json
@@ -1,7 +1,8 @@
 {
   "ml.get_trained_models":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-inference.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-inference.html",
+      "description":"Retrieves configuration information for a trained inference model."
     },
     "stability":"experimental",
     "url":{
@@ -39,26 +40,26 @@
         "description":"Should the full model definition be included in the results. These definitions can be large. So be cautious when including them. Defaults to false.",
         "default":false
       },
-      "decompress_definition": {
-        "type": "boolean",
-        "required": false,
-        "default": true,
-        "description": "Should the model definition be decompressed into valid JSON or returned in a custom compressed format. Defaults to true."
+      "decompress_definition":{
+        "type":"boolean",
+        "required":false,
+        "default":true,
+        "description":"Should the model definition be decompressed into valid JSON or returned in a custom compressed format. Defaults to true."
       },
       "from":{
-        "required": false,
+        "required":false,
         "type":"int",
         "description":"skips a number of trained models",
         "default":0
       },
       "size":{
-        "required": false,
+        "required":false,
         "type":"int",
         "description":"specifies a max number of trained models to get",
         "default":100
       },
-      "tags": {
-        "required": false,
+      "tags":{
+        "required":false,
         "type":"list",
         "description":"A comma-separated list of tags that the model must have."
       }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models_stats.json
index c00b33f2ea9c..93e94452130b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_trained_models_stats.json
@@ -1,7 +1,8 @@
 {
   "ml.get_trained_models_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-inference-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-inference-stats.html",
+      "description":"Retrieves usage information for trained inference models."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.info.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.info.json
index 5fa134e1781b..22c15971eb91 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.info.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.info.json
@@ -1,7 +1,8 @@
 {
   "ml.info":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-ml-info.html",
+      "description":"Returns defaults and limits used by machine learning."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.open_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.open_job.json
index dfa36ad2b0d6..436d45418062 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.open_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.open_job.json
@@ -1,7 +1,8 @@
 {
   "ml.open_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-open-job.html",
+      "description":"Opens one or more anomaly detection jobs."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_calendar_events.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_calendar_events.json
index 3bb25c4eaa68..42dcb38f66a1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_calendar_events.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_calendar_events.json
@@ -1,7 +1,8 @@
 {
   "ml.post_calendar_events":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-post-calendar-event.html",
+      "description":"Posts scheduled events in a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_data.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_data.json
index 93e543698558..52b8f15805ba 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_data.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.post_data.json
@@ -1,7 +1,8 @@
 {
   "ml.post_data":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-post-data.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-post-data.html",
+      "description":"Sends data to an anomaly detection job for analysis."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.preview_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.preview_datafeed.json
index b1d4437dcca7..30926f4abab5 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.preview_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.preview_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.preview_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-preview-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-preview-datafeed.html",
+      "description":"Previews a datafeed."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar.json
index 57c5b3769ce6..88b747a7aeae 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar.json
@@ -1,7 +1,8 @@
 {
   "ml.put_calendar":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-calendar.html",
+      "description":"Instantiates a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar_job.json
index f10a9a438465..3f478243b12b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_calendar_job.json
@@ -1,7 +1,8 @@
 {
   "ml.put_calendar_job":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-calendar-job.html",
+      "description":"Adds an anomaly detection job to a calendar."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_data_frame_analytics.json
index fd2b01c022f9..6c246074f579 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "ml.put_data_frame_analytics":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-dfanalytics.html",
+      "description":"Instantiates a data frame analytics job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_datafeed.json
index 30985f178005..29d5bbb2b180 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.put_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-datafeed.html",
+      "description":"Instantiates a datafeed."
     },
     "stability":"stable",
     "url":{
@@ -24,7 +25,7 @@
       "description":"The datafeed config",
       "required":true
     },
-    "params": {
+    "params":{
       "ignore_unavailable":{
         "type":"boolean",
         "description":"Ignore unavailable indexes (default: false)"
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_filter.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_filter.json
index f5d6c476a4cb..647e9963a3c9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_filter.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_filter.json
@@ -1,7 +1,8 @@
 {
   "ml.put_filter":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-filter.html",
+      "description":"Instantiates a filter."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_job.json
index 1581710125fe..4a15a7554629 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_job.json
@@ -1,7 +1,8 @@
 {
   "ml.put_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html",
+      "description":"Instantiates an anomaly detection job."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_trained_model.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_trained_model.json
index a58fa1354074..f69756b55e9b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_trained_model.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.put_trained_model.json
@@ -1,7 +1,8 @@
 {
   "ml.put_trained_model":{
     "documentation":{
-      "url":"TODO"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-inference.html",
+      "description":"Creates an inference trained model."
     },
     "stability":"experimental",
     "url":{
@@ -20,7 +21,7 @@
         }
       ]
     },
-    "body": {
+    "body":{
       "description":"The trained model configuration",
       "required":true
     }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.revert_model_snapshot.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.revert_model_snapshot.json
index 64900d722301..3c0ae924aa44 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.revert_model_snapshot.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.revert_model_snapshot.json
@@ -1,7 +1,8 @@
 {
   "ml.revert_model_snapshot":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-revert-snapshot.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-revert-snapshot.html",
+      "description":"Reverts to a specific snapshot."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.set_upgrade_mode.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.set_upgrade_mode.json
index 071a0856b0dd..3092b48be2a5 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.set_upgrade_mode.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.set_upgrade_mode.json
@@ -1,7 +1,8 @@
 {
   "ml.set_upgrade_mode":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-set-upgrade-mode.html",
+      "description":"Sets a cluster wide upgrade_mode setting that prepares machine learning indices for an upgrade."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_data_frame_analytics.json
index 1ae392764cd1..b075a6290705 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "ml.start_data_frame_analytics":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-dfanalytics.html",
+      "description":"Starts a data frame analytics job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_datafeed.json
index a835b02c96c7..1348478c32f1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.start_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.start_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-start-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-start-datafeed.html",
+      "description":"Starts one or more datafeeds."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_data_frame_analytics.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_data_frame_analytics.json
index 86294610b1f4..ec0f95bcce84 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_data_frame_analytics.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_data_frame_analytics.json
@@ -1,7 +1,8 @@
 {
   "ml.stop_data_frame_analytics":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-dfanalytics.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-dfanalytics.html",
+      "description":"Stops one or more data frame analytics jobs."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_datafeed.json
index fc4b20faddf2..e7fcadce262d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.stop_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.stop_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-stop-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-stop-datafeed.html",
+      "description":"Stops one or more datafeeds."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_datafeed.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_datafeed.json
index f820933c7695..29397cedef42 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_datafeed.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_datafeed.json
@@ -1,7 +1,8 @@
 {
   "ml.update_datafeed":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-datafeed.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-datafeed.html",
+      "description":"Updates certain properties of a datafeed."
     },
     "stability":"stable",
     "url":{
@@ -24,7 +25,7 @@
       "description":"The datafeed update settings",
       "required":true
     },
-    "params": {
+    "params":{
       "ignore_unavailable":{
         "type":"boolean",
         "description":"Ignore unavailable indexes (default: false)"
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_filter.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_filter.json
index f6f155b04eea..b945940f21cf 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_filter.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_filter.json
@@ -1,7 +1,8 @@
 {
   "ml.update_filter":{
     "documentation":{
-      "url":null
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-filter.html",
+      "description":"Updates the description of a filter, adds items, or removes items."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_job.json
index 78d9491398b4..ddc391138272 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_job.json
@@ -1,7 +1,8 @@
 {
   "ml.update_job":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-job.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-job.html",
+      "description":"Updates certain properties of an anomaly detection job."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_model_snapshot.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_model_snapshot.json
index b49a0f912ca3..08e17529f5a1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_model_snapshot.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.update_model_snapshot.json
@@ -1,7 +1,8 @@
 {
   "ml.update_model_snapshot":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-snapshot.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-update-snapshot.html",
+      "description":"Updates certain properties of a snapshot."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
index c78d1aad6fd1..ffbede6b1e38 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate.json
@@ -1,7 +1,8 @@
 {
   "ml.validate":{
     "documentation":{
-      "url":null
+      "url":null,
+      "description":"Validates an anomaly detection job."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
index ddb663793150..f4cee6d5c270 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.validate_detector.json
@@ -1,7 +1,8 @@
 {
   "ml.validate_detector":{
     "documentation":{
-      "url":null
+      "url":null,
+      "description":"Validates an anomaly detection detector."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/monitoring.bulk.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/monitoring.bulk.json
index 698b818b450a..ff48044cc9d1 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/monitoring.bulk.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/monitoring.bulk.json
@@ -1,7 +1,8 @@
 {
   "monitoring.bulk":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/monitor-elasticsearch-cluster.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/monitor-elasticsearch-cluster.html",
+      "description":"Used by the monitoring features to send monitoring data."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.delete_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.delete_job.json
index 6e90cd81efd6..574ae3df385f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.delete_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.delete_job.json
@@ -1,7 +1,8 @@
 {
   "rollup.delete_job":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-delete-job.html",
+      "description":"Deletes an existing rollup job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_jobs.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_jobs.json
index cf1ae43fafd2..f585edfdef8c 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_jobs.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_jobs.json
@@ -1,7 +1,8 @@
 {
   "rollup.get_jobs":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-job.html",
+      "description":"Retrieves the configuration, stats, and status of rollup jobs."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_caps.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_caps.json
index 4944a9442cd0..d139899ae497 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_caps.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_caps.json
@@ -1,7 +1,8 @@
 {
   "rollup.get_rollup_caps":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-rollup-caps.html",
+      "description":"Returns the capabilities of any rollup jobs that have been configured for a specific index or index pattern."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json
index e6d85ea99eee..33bb81f9a1d6 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.get_rollup_index_caps.json
@@ -1,7 +1,8 @@
 {
   "rollup.get_rollup_index_caps":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-get-rollup-index-caps.html",
+      "description":"Returns the rollup capabilities of all jobs inside of a rollup index (e.g. the index where rollup data is stored)."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.put_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.put_job.json
index 0f82970a0c86..8fb10631573e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.put_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.put_job.json
@@ -1,7 +1,8 @@
 {
   "rollup.put_job":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-put-job.html",
+      "description":"Creates a rollup job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.rollup_search.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.rollup_search.json
index e04ef3e36ed9..2ca1b53fb25d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.rollup_search.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.rollup_search.json
@@ -1,13 +1,14 @@
 {
   "rollup.rollup_search":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-search.html",
+      "description":"Enables searching rolled-up data using the standard query DSL."
     },
     "stability":"experimental",
     "url":{
       "paths":[
         {
-          "path":"{index}/_rollup_search",
+          "path":"/{index}/_rollup_search",
           "methods":[
             "GET",
             "POST"
@@ -20,7 +21,7 @@
           }
         },
         {
-          "path":"{index}/{type}/_rollup_search",
+          "path":"/{index}/{type}/_rollup_search",
           "methods":[
             "GET",
             "POST"
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.start_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.start_job.json
index c8d5833e5661..b42924d08e44 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.start_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.start_job.json
@@ -1,7 +1,8 @@
 {
   "rollup.start_job":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-start-job.html",
+      "description":"Starts an existing, stopped rollup job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.stop_job.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.stop_job.json
index 46b0212e86ad..d2b65fb84a29 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.stop_job.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/rollup.stop_job.json
@@ -1,7 +1,8 @@
 {
   "rollup.stop_job":{
     "documentation":{
-      "url":""
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/rollup-stop-job.html",
+      "description":"Stops an existing, started rollup job."
     },
     "stability":"experimental",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.authenticate.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.authenticate.json
index 2864641c6ad8..35455c78151d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.authenticate.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.authenticate.json
@@ -1,7 +1,8 @@
 {
   "security.authenticate":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-authenticate.html",
+      "description":"Enables authentication as a user and retrieve information about the authenticated user."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.change_password.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.change_password.json
index abfc9bb5d21a..1195d82b6889 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.change_password.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.change_password.json
@@ -1,7 +1,8 @@
 {
   "security.change_password":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-change-password.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-change-password.html",
+      "description":"Changes the passwords of users in the native realm and built-in users."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_realms.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_realms.json
index 179e6ea64a46..1e0119af5121 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_realms.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_realms.json
@@ -1,7 +1,8 @@
 {
   "security.clear_cached_realms":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html",
+      "description":"Evicts users from the user cache. Can completely clear the cache or evict specific users."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_roles.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_roles.json
index 883689ec25f2..72c8ac212498 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_roles.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.clear_cached_roles.json
@@ -1,7 +1,8 @@
 {
   "security.clear_cached_roles":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html",
+      "description":"Evicts roles from the native role cache."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.create_api_key.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.create_api_key.json
index cc7e9f65f94d..e6da65981a31 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.create_api_key.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.create_api_key.json
@@ -1,7 +1,8 @@
 {
   "security.create_api_key":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html",
+      "description":"Creates an API key for access without requiring basic authentication."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_privileges.json
index 1707372c424d..8069ed790fa9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.delete_privileges":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-privilege.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-privilege.html",
+      "description":"Removes application privileges."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role.json
index 1b739912128a..d718ec777a47 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role.json
@@ -1,7 +1,8 @@
 {
   "security.delete_role":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role.html",
+      "description":"Removes roles in the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role_mapping.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role_mapping.json
index 231390e5daee..ee0bc3ad641f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role_mapping.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_role_mapping.json
@@ -1,7 +1,8 @@
 {
   "security.delete_role_mapping":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role-mapping.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role-mapping.html",
+      "description":"Removes role mappings."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_user.json
index 99ec88f3493d..7c10cd3fd1be 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_user.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.delete_user.json
@@ -1,7 +1,8 @@
 {
   "security.delete_user":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-user.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-user.html",
+      "description":"Deletes users from the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.disable_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.disable_user.json
index 925b41407443..4877870bcd41 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.disable_user.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.disable_user.json
@@ -1,7 +1,8 @@
 {
   "security.disable_user":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-disable-user.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-disable-user.html",
+      "description":"Disables users in the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.enable_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.enable_user.json
index 83d14e82aafe..58d7f64f1142 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.enable_user.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.enable_user.json
@@ -1,7 +1,8 @@
 {
   "security.enable_user":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user.html",
+      "description":"Enables users in the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_api_key.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_api_key.json
index 028f3a51aea9..8c508f25d32f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_api_key.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_api_key.json
@@ -1,7 +1,8 @@
 {
   "security.get_api_key":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-api-key.html",
+      "description":"Retrieves information for one or more API keys."
     },
     "stability":"stable",
     "url":{
@@ -31,9 +32,9 @@
         "type":"string",
         "description":"realm name of the user who created this API key to be retrieved"
       },
-      "owner": {
+      "owner":{
         "type":"boolean",
-        "default": false,
+        "default":false,
         "description":"flag to query API keys owned by the currently authenticated user"
       }
     }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_builtin_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_builtin_privileges.json
index 2b61c4baba58..cd20a32be633 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_builtin_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_builtin_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.get_builtin_privileges":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-builtin-privileges.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-builtin-privileges.html",
+      "description":"Retrieves the list of cluster privileges and index privileges that are available in this version of Elasticsearch."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_privileges.json
index 23acd2d54bed..b216ac98c749 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.get_privileges":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html",
+      "description":"Retrieves application privileges."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role.json
index 0c142d92fd81..9c52878a5f9b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role.json
@@ -1,7 +1,8 @@
 {
   "security.get_role":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role.html",
+      "description":"Retrieves roles in the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role_mapping.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role_mapping.json
index 1ff7eda328de..4b98173b5c14 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role_mapping.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_role_mapping.json
@@ -1,7 +1,8 @@
 {
   "security.get_role_mapping":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role-mapping.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role-mapping.html",
+      "description":"Retrieves role mappings."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_token.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_token.json
index 09b76b906856..84a87a75d62f 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_token.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_token.json
@@ -1,7 +1,8 @@
 {
   "security.get_token":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-token.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-token.html",
+      "description":"Creates a bearer token for access without requiring basic authentication."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user.json
index ceb4c3a83b18..cb1c64ce8983 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user.json
@@ -1,7 +1,8 @@
 {
   "security.get_user":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-user.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-user.html",
+      "description":"Retrieves information about users in the native realm and built-in users."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user_privileges.json
index c0a404ff3429..7dacebae2d63 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.get_user_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.get_user_privileges":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-privileges.html",
+      "description":"Retrieves application privileges."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.has_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.has_privileges.json
index cafd31cd4a84..d19f4158f911 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.has_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.has_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.has_privileges":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html",
+      "description":"Determines whether the specified user has a specified list of privileges."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_api_key.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_api_key.json
index 827b3da9635c..15a7e5437e1b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_api_key.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_api_key.json
@@ -1,7 +1,8 @@
 {
   "security.invalidate_api_key":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-api-key.html",
+      "description":"Invalidates one or more API keys."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_token.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_token.json
index 73cbc86722cd..75a3283c1e68 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_token.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.invalidate_token.json
@@ -1,7 +1,8 @@
 {
   "security.invalidate_token":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-token.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-token.html",
+      "description":"Invalidates one or more access tokens or refresh tokens."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_privileges.json
index fd58a4109d9c..36f5bfa2f8d0 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_privileges.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_privileges.json
@@ -1,7 +1,8 @@
 {
   "security.put_privileges":{
     "documentation":{
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-privileges.html",
+      "description":"Adds or updates application privileges."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role.json
index 718472e04d51..61aeca519c9d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role.json
@@ -1,7 +1,8 @@
 {
   "security.put_role":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html",
+      "description":"Adds and updates roles in the native realm."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role_mapping.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role_mapping.json
index f083bbc64255..167c13c93671 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role_mapping.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_role_mapping.json
@@ -1,7 +1,8 @@
 {
   "security.put_role_mapping":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html",
+      "description":"Creates and updates role mappings."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_user.json
index d1441cbb23b1..70dff7aba4a7 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_user.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.put_user.json
@@ -1,7 +1,8 @@
 {
   "security.put_user":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
+      "description":"Adds and updates users in the native realm. These users are commonly referred to as native users."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json
index 93a45abd91f6..07b21da6c7a3 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "slm.delete_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-delete-policy.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-delete-policy.html",
+      "description":"Deletes an existing snapshot lifecycle policy."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json
index 963a6e0577b4..74f574928679 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "slm.execute_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-lifecycle.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-lifecycle.html",
+      "description":"Immediately creates a snapshot according to the lifecycle policy, without waiting for the scheduled time."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_retention.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_retention.json
index e6d21db0716d..6448a1d20c61 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_retention.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_retention.json
@@ -1,7 +1,8 @@
 {
   "slm.execute_retention":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-retention.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-retention.html",
+      "description":"Deletes any snapshots that are expired according to the policy's retention rules."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json
index a4a3b436f179..4a208ebb2a7e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "slm.get_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-policy.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-policy.html",
+      "description":"Retrieves one or more snapshot lifecycle policy definitions and information about the latest snapshot attempts."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json
index 747bdccdba7c..b4fe2f23a7e6 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json
@@ -1,7 +1,8 @@
 {
   "slm.get_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/slm-api-get-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/slm-api-get-stats.html",
+      "description":"Returns global and policy-level statistics about actions taken by snapshot lifecycle management."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_status.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_status.json
index 4ea6089ce438..382402432136 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_status.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_status.json
@@ -1,7 +1,8 @@
 {
   "slm.get_status":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-status.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-status.html",
+      "description":"Retrieves the status of snapshot lifecycle management (SLM)."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json
index ce10a7b482c0..9f2b8fe1b237 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json
@@ -1,7 +1,8 @@
 {
   "slm.put_lifecycle":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html",
+      "description":"Creates or updates a snapshot lifecycle policy."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.start.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.start.json
index 0ceb74e92795..8d06c51d3e89 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.start.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.start.json
@@ -1,7 +1,8 @@
 {
   "slm.start":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-start.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-start.html",
+      "description":"Turns on snapshot lifecycle management (SLM)."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.stop.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.stop.json
index b052f4bf975d..e35ec0aaa886 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.stop.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.stop.json
@@ -1,7 +1,8 @@
 {
   "slm.stop":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-stop.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-stop.html",
+      "description":"Turns off snapshot lifecycle management (SLM)."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/sql.query.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/sql.query.json
index 1c32b7b5b285..f36ca0068ec7 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/sql.query.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/sql.query.json
@@ -2,7 +2,7 @@
   "sql.query":{
     "documentation":{
       "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/sql-rest-overview.html",
-      "description":"Executes an SQL request"
+      "description":"Executes a SQL request"
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/ssl.certificates.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/ssl.certificates.json
index bc4369458c23..0dd7bce01046 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/ssl.certificates.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/ssl.certificates.json
@@ -1,7 +1,8 @@
 {
   "ssl.certificates":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-ssl.html",
+      "description":"Retrieves information about the X.509 certificates used to encrypt communications in the cluster."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.delete_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.delete_transform.json
index 1260dbca993f..7378f247135e 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.delete_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.delete_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.delete_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/delete-transform.html",
+      "description":"Deletes an existing transform."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform.json
index 5f9c6bd692e3..1ab97aa6a18d 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.get_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform.html",
+      "description":"Retrieves configuration information for transforms."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform_stats.json
index 9c2854f3f8d6..1691d550da53 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform_stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.get_transform_stats.json
@@ -1,7 +1,8 @@
 {
   "transform.get_transform_stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-transform-stats.html",
+      "description":"Retrieves usage information for transforms."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.preview_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.preview_transform.json
index d5081edc63d5..83ecc006e9ba 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.preview_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.preview_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.preview_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/preview-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/preview-transform.html",
+      "description":"Previews a transform."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.put_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.put_transform.json
index 65ec19b1f079..47ade4a0dd35 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.put_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.put_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.put_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/put-transform.html",
+      "description":"Instantiates a transform."
     },
     "stability":"stable",
     "url":{
@@ -20,11 +21,11 @@
         }
       ]
     },
-    "params": {
-      "defer_validation": {
-        "type": "boolean",
-        "required": false,
-        "description": "If validations should be deferred until transform starts, defaults to false."
+    "params":{
+      "defer_validation":{
+        "type":"boolean",
+        "required":false,
+        "description":"If validations should be deferred until transform starts, defaults to false."
       }
     },
     "body":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.start_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.start_transform.json
index b95115b86f44..9316e500d658 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.start_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.start_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.start_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/start-transform.html",
+      "description":"Starts one or more transforms."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.stop_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.stop_transform.json
index edbfb665c231..497219813b40 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.stop_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.stop_transform.json
@@ -1,7 +1,8 @@
 {
   "transform.stop_transform":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-transform.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/stop-transform.html",
+      "description":"Stops one or more transforms."
     },
     "stability":"stable",
     "url":{
@@ -20,31 +21,31 @@
         }
       ]
     },
-    "params": {
-      "force": {
-        "type": "boolean",
-        "required": false,
-        "description": "Whether to force stop a failed transform or not. Default to false"
+    "params":{
+      "force":{
+        "type":"boolean",
+        "required":false,
+        "description":"Whether to force stop a failed transform or not. Default to false"
       },
-      "wait_for_completion": {
-        "type": "boolean",
-        "required": false,
-        "description": "Whether to wait for the transform to fully stop before returning or not. Default to false"
+      "wait_for_completion":{
+        "type":"boolean",
+        "required":false,
+        "description":"Whether to wait for the transform to fully stop before returning or not. Default to false"
       },
-      "timeout": {
-        "type": "time",
-        "required": false,
-        "description": "Controls the time to wait until the transform has stopped. Default to 30 seconds"
+      "timeout":{
+        "type":"time",
+        "required":false,
+        "description":"Controls the time to wait until the transform has stopped. Default to 30 seconds"
       },
-      "allow_no_match": {
-        "type": "boolean",
-        "required": false,
-        "description": "Whether to ignore if a wildcard expression matches no transforms. (This includes `_all` string or when no transforms have been specified)"
+      "allow_no_match":{
+        "type":"boolean",
+        "required":false,
+        "description":"Whether to ignore if a wildcard expression matches no transforms. (This includes `_all` string or when no transforms have been specified)"
       },
-      "wait_for_checkpoint": {
-        "type": "boolean",
-        "required": false,
-        "description": "Whether to wait for the transform to reach a checkpoint before stopping. Default to false"
+      "wait_for_checkpoint":{
+        "type":"boolean",
+        "required":false,
+        "description":"Whether to wait for the transform to reach a checkpoint before stopping. Default to false"
       }
     }
   }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.update_transform.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.update_transform.json
index fff24a327823..fe74376e833a 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.update_transform.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/transform.update_transform.json
@@ -1,34 +1,37 @@
 {
-  "transform.update_transform": {
-    "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/update-transform.html"
+  "transform.update_transform":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/update-transform.html",
+      "description":"Updates certain properties of a transform."
     },
-    "stability": "stable",
-    "url": {
-      "paths": [
+    "stability":"stable",
+    "url":{
+      "paths":[
         {
-          "path": "/_transform/{transform_id}/_update",
-          "methods": [ "POST" ],
-          "parts": {
-            "transform_id": {
-              "type": "string",
-              "required": true,
-              "description": "The id of the transform."
+          "path":"/_transform/{transform_id}/_update",
+          "methods":[
+            "POST"
+          ],
+          "parts":{
+            "transform_id":{
+              "type":"string",
+              "required":true,
+              "description":"The id of the transform."
             }
           }
         }
       ]
     },
-    "params": {
-      "defer_validation": {
-        "type": "boolean",
-        "required": false,
-        "description": "If validations should be deferred until transform starts, defaults to false."
+    "params":{
+      "defer_validation":{
+        "type":"boolean",
+        "required":false,
+        "description":"If validations should be deferred until transform starts, defaults to false."
       }
     },
-    "body": {
-      "description" : "The update transform definition",
-      "required": true
+    "body":{
+      "description":"The update transform definition",
+      "required":true
     }
   }
 }
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.ack_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.ack_watch.json
index 22c481a52860..0b9126a8306c 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.ack_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.ack_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.ack_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-ack-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-ack-watch.html",
+      "description":"Acknowledges a watch, manually throttling the execution of the watch's actions."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.activate_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.activate_watch.json
index bfbf933cf0db..d0a892debee5 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.activate_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.activate_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.activate_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-activate-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-activate-watch.html",
+      "description":"Activates a currently inactive watch."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.deactivate_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.deactivate_watch.json
index 56ee8ed82f86..90385dfd0d45 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.deactivate_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.deactivate_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.deactivate_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-deactivate-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-deactivate-watch.html",
+      "description":"Deactivates a currently active watch."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.delete_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.delete_watch.json
index a337ab0691bf..c42ec9cb0104 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.delete_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.delete_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.delete_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-delete-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-delete-watch.html",
+      "description":"Removes a watch from Watcher."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.execute_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.execute_watch.json
index dc06847708e4..3704eb4aeda6 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.execute_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.execute_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.execute_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-execute-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-execute-watch.html",
+      "description":"Forces the execution of a stored watch."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.get_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.get_watch.json
index ed84a6c29ad2..e81dcd7e3895 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.get_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.get_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.get_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-get-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-get-watch.html",
+      "description":"Retrieves a watch by its ID."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.put_watch.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.put_watch.json
index b0a025b0c95e..6aa29c5f9ed2 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.put_watch.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.put_watch.json
@@ -1,7 +1,8 @@
 {
   "watcher.put_watch":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html",
+      "description":"Creates a new watch, or updates an existing one."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.start.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.start.json
index 998e4a769930..eb393a25c1bf 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.start.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.start.json
@@ -1,7 +1,8 @@
 {
   "watcher.start":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html",
+      "description":"Starts Watcher if it is not already running."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stats.json
index 9ef0f2320459..75854017f0b9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stats.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stats.json
@@ -1,7 +1,8 @@
 {
   "watcher.stats":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stats.html",
+      "description":"Retrieves the current Watcher metrics."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stop.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stop.json
index 1591e0be341e..c5014be0ab0b 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stop.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/watcher.stop.json
@@ -1,7 +1,8 @@
 {
   "watcher.stop":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stop.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stop.html",
+      "description":"Stops Watcher if it is running."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.info.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.info.json
index 49914c092d24..2ccb1beda7d9 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.info.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.info.json
@@ -1,7 +1,8 @@
 {
   "xpack.info":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/info-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/info-api.html",
+      "description":"Retrieves information about the installed X-Pack features."
     },
     "stability":"stable",
     "url":{
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.usage.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.usage.json
index ebd546b0f002..2f99c477d2da 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.usage.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.usage.json
@@ -1,7 +1,8 @@
 {
   "xpack.usage":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/usage-api.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/usage-api.html",
+      "description":"Retrieves usage information about the installed X-Pack features."
     },
     "stability":"stable",
     "url":{