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 6ee594b099c43..1ba12b00c8178 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 7e79b7cc2c977..bd7454b8046b8 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 d4a7eb3b051d2..a92189134f88f 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 2a21ff3725b6a..894b141f2f3b3 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 9be09b49cc54c..8641c18382dfc 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 16e8d0a0cfab3..aa770ee9d9f2e 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 5a45392d9ee11..a5e06cb88901b 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 e238c4fc38afc..5bfdd985a0a85 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 4a1dea974f750..68e325446d3dc 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 1d216dcb0b322..ca4783368d1b1 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 299c4f705d292..86fa8a60db43b 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 0000000000000..0e7b84fb39bf1
--- /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 10416b04ce5c1..70794f4a8b764 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 4207ebba0a464..76c4650ab0790 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 c45c31c134da3..1f4d0b9a6bf3a 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 e6ecd75312d56..26ce055aad35d 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 072ba74f6f8e6..ec041788fffc6 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 d750ff56b8972..c7f4cce0cd576 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 f62a46ba34133..53187760d5cd9 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 77875d03a2f78..e129d3201abe6 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 98a2fcac1c281..66b55d9a4bbcc 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 411bc10db946a..f9e70a1f6ac9a 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 830c3d7e02cb0..be3dfc752175d 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 dbe5f53f24783..858eab0b9180e 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 aecfd50a6a90d..1abe53bd21c2f 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 4d4af1a607253..d0df2f164feb0 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 8d34c1e597116..b89587d2611f5 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 9e76b83bb904f..711e3deb31938 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 54b4576575987..f45947b1a8721 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 7edcb62903158..79a498da16dc7 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 96b77cb82e93f..e6c3d268b1644 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 c6b3135fd7f3c..de1945f347b64 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 fcf36bf188ae3..dc70f1a3971d7 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 1730a728c5e34..c5db9219a395d 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 2949ceb444995..28c90b604f685 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 466e687bd19eb..17f333861c5dc 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 eb5dd8d5d2f6f..7822f3ce5c043 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 1ae012d28cbed..90b9b9173aaa3 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 27256eb782f63..ce86e733ba51b 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 f47bd61726e84..fd9e25619d766 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 434375a9fabdd..8938ec5bc8e1d 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 d1c0bb2456a78..97e1821b53c23 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 2d4fd1a7baf27..f7a1830251084 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 90413423a9dc0..a448d91062cc9 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 ab0d699dbf9f9..32bdf01f34002 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 c23bec02ab0a0..1078715844361 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 69175d5563475..153ee42b7a7be 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 68c105a41d7e4..4e56583722bb1 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 253ab219d5280..575ba9c690c98 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 50c15a9b6ee1b..59c14b3c9e2b8 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 e00cc9aceb9eb..9a8f11ae5bc00 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 231748795613b..6846d92b97e04 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 0e94c22596965..1808e903a68f8 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 1f46cd2e0053d..c3b397ba8a8e8 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 b33521cf5127d..260292118a7b2 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 f2b843017e671..e39c95f68d7e7 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 c25a84521405c..ab957713db017 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 f6dd48beac5c7..56ca5a4ad4c4e 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 c49bbf327db30..9604499cecaf5 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 28a051012fa17..2966db1d015b3 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 75d871a5145d1..2c0214976b30f 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 651a79d0c42a6..bc527f6f19585 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 9c369c384c2fd..153f38b264ff5 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 f3fc15845e9bd..1820affbcf90f 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 b3d10f1e1c088..d29bc9ffba6c2 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 072608982da91..71c854b4f5d97 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 4b53ebeaa72a9..2b637f8577b45 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 3aa928ec15034..855a90cfe2a78 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 a28b45dc8dea5..ebf5f71880110 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 6be7d2006410c..ca19147c0525b 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 7627a08a6ac6d..f51ebf62b895d 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 4614965a098c3..7cf3501b26551 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 a6b70a1427882..aa6e2d310a5ff 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 5d88f42b7641a..075ddcac10f5a 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 c85cf60651a24..4a077b375e774 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 9df83f1b82572..d3abeaa6c120c 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 598cad6b0bc33..ac38a7a344938 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 bcb0fe310b9a6..9556a0fe472b5 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 c53dd95e81557..08f4a79e0f86e 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 bdcea04d16ff6..eb820441fddfd 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 b5735da3cc12d..b6caa438acd10 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 01e935bd4ad59..27d24cd775941 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 6eaa707a4969f..4a024f937225f 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 6d7770fcd4f49..9190f52adba8c 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 6969cf9a49f13..9210862db960a 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 46b4f5afb0514..13594031fc609 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 695935f9fb86c..3e2f7f365babc 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 71475feb6f921..fa5c1ffe7c8ca 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 1be237653624e..90f7cedea5409 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 f0f57b05ef1fd..0bb10780d1df2 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 d863f83387520..ec6268acb49e5 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 c089cf87b5e36..973382de630a3 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 82567d75426c9..80b4649453f7f 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 5390aab47c975..1c35de865e027 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 cf390848312f0..3c0177f66d1fc 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 c17c8eb194fdf..e475f216dbc18 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 20672c04b900e..b56518c524e6d 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 8730f7b185ece..25f68ab014afa 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 8f4f695290797..29df54a463074 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 fa456d9130d6b..58c595276e886 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 8a2f4885e9fe4..5dafaa43d8e34 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 23239ae748c7a..aac547a178327 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 fc87d924c2924..9d8658972e6e5 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 7c41285bd1ca8..3b5b42795bda9 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 c00b33f2ea9ca..93e94452130bf 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 5fa134e1781b3..22c15971eb916 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 dfa36ad2b0d68..436d454180620 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 3bb25c4eaa683..42dcb38f66a18 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 93e543698558a..52b8f15805bab 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 b1d4437dcca75..30926f4abab50 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 57c5b3769ce6e..88b747a7aeaee 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 f10a9a438465a..3f478243b12b1 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 fd2b01c022f91..6c246074f579a 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 30985f178005e..29d5bbb2b1800 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 f5d6c476a4cbc..647e9963a3c9e 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 1581710125fe4..4a15a7554629d 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 a58fa13540748..f69756b55e9be 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 64900d7223018..3c0ae924aa444 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 071a0856b0dda..3092b48be2a56 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 1ae392764cd19..b075a62907050 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 a835b02c96c7a..1348478c32f14 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 86294610b1f49..ec0f95bcce84b 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 fc4b20faddf27..e7fcadce262d6 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 f820933c76955..29397cedef42d 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 f6f155b04eead..b945940f21cf3 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 78d9491398b4f..ddc391138272d 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 b49a0f912ca30..08e17529f5a1c 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 c78d1aad6fd19..ffbede6b1e387 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 ddb6637931500..f4cee6d5c270d 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 698b818b450af..ff48044cc9d1b 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 6e90cd81efd68..574ae3df385fd 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 cf1ae43fafd2b..f585edfdef8c8 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 4944a9442cd09..d139899ae4978 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 e6d85ea99eee9..33bb81f9a1d64 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 0f82970a0c86d..8fb10631573e1 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 e04ef3e36ed99..2ca1b53fb25d3 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 c8d5833e56611..b42924d08e445 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 46b0212e86adc..d2b65fb84a292 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 2864641c6ad8d..35455c78151dc 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 abfc9bb5d21ae..1195d82b6889e 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 179e6ea64a467..1e0119af51215 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 883689ec25f24..72c8ac2124987 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 cc7e9f65f94df..e6da65981a317 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 1707372c424d8..8069ed790fa9f 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 1b739912128a0..d718ec777a475 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 231390e5daee3..ee0bc3ad641f7 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 99ec88f3493db..7c10cd3fd1be7 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 925b414074437..4877870bcd41a 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 83d14e82aafe9..58d7f64f1142a 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 028f3a51aea9e..8c508f25d32f7 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 2b61c4baba582..cd20a32be633f 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 23acd2d54beda..b216ac98c7492 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 0c142d92fd811..9c52878a5f9b5 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 1ff7eda328dee..4b98173b5c146 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 09b76b9068569..84a87a75d62ff 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 ceb4c3a83b18f..cb1c64ce89832 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 c0a404ff34294..7dacebae2d633 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 cafd31cd4a84c..d19f4158f9115 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 827b3da9635cf..15a7e5437e1b8 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 73cbc86722cd1..75a3283c1e68d 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 fd58a4109d9c9..36f5bfa2f8d08 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 718472e04d519..61aeca519c9da 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 f083bbc642550..167c13c936717 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 d1441cbb23b16..70dff7aba4a7a 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 93a45abd91f65..07b21da6c7a34 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 963a6e0577b41..74f5749286790 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 e6d21db0716d1..6448a1d20c61b 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 a4a3b436f179b..4a208ebb2a7e5 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 747bdccdba7c6..b4fe2f23a7e6f 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 4ea6089ce438a..3824024321360 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 ce10a7b482c0c..9f2b8fe1b2378 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 0ceb74e927955..8d06c51d3e899 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 b052f4bf975d9..e35ec0aaa8865 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 1c32b7b5b2852..f36ca0068ec72 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 bc4369458c238..0dd7bce010464 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 1260dbca993f2..7378f247135ed 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 5f9c6bd692e33..1ab97aa6a18db 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 9c2854f3f8d67..1691d550da531 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 d5081edc63d51..83ecc006e9ba0 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 65ec19b1f0796..47ade4a0dd357 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 b95115b86f447..9316e500d658a 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 edbfb665c2311..497219813b40e 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 fff24a3278230..fe74376e833a1 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 22c481a52860f..0b9126a8306cf 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 bfbf933cf0db9..d0a892debee50 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 56ee8ed82f86b..90385dfd0d452 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 a337ab0691bf8..c42ec9cb01041 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 dc06847708e40..3704eb4aeda61 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 ed84a6c29ad25..e81dcd7e3895f 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 b0a025b0c95ec..6aa29c5f9ed2e 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 998e4a7699300..eb393a25c1bf3 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 9ef0f23204599..75854017f0b9b 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 1591e0be341ef..c5014be0ab0b7 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 49914c092d24d..2ccb1beda7d96 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 ebd546b0f0027..2f99c477d2da4 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":{