Update rest API specs (#54252)

This commit updates the rest API specs to validate against a
JSON schema for the specifications. Most updates are to add
a description, whilst others fix typos and unify conventions
e.g. deprecations, descriptions, urls starting with /. The schema 
conforms to draft-07 JSON schema.

rest-api-spec/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."
       }
     }

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":{

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":{

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"
       }
     }

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":{

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",

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",

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":{

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":{

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": {}
+    }
   }
 }

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":{

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"
+        }
+    }
+}

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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
     }
   }
 }

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": {

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": {

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": {

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": {

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": {

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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
       }
     }
   }

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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"
       }
     }

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":{

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":{

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":{

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":{

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":{

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
     }
   }
 }

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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":{

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"
             }
           }
         }

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":{

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":{