update _common.json format

API spec now use an object for the documentation field. _common was not updated yet. This commit updates _common.json and its corresponding parser.

Closes #46744

Author: javanna

rest-api-spec/src/main/resources/rest-api-spec/api/_common.json

@@ -1,6 +1,8 @@
 {
-  "description": "Parameters that are accepted by all API endpoints.",
-  "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html",
+  "documentation" : {
+    "url": "Parameters that are accepted by all API endpoints.",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html"
+  },
   "params": {
     "pretty": {
       "type": "boolean",

test/framework/src/main/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestSpec.java

@@ -18,6 +18,13 @@
  */
 package org.elasticsearch.test.rest.yaml.restspec;
 
+import org.elasticsearch.common.ParsingException;
+import org.elasticsearch.common.io.PathUtils;
+import org.elasticsearch.common.xcontent.LoggingDeprecationHandler;
+import org.elasticsearch.common.xcontent.NamedXContentRegistry;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.common.xcontent.json.JsonXContent;
+
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.UncheckedIOException;
@@ -30,12 +37,6 @@
 import java.util.Set;
 import java.util.stream.Stream;
 
-import org.elasticsearch.common.io.PathUtils;
-import org.elasticsearch.common.xcontent.LoggingDeprecationHandler;
-import org.elasticsearch.common.xcontent.NamedXContentRegistry;
-import org.elasticsearch.common.xcontent.XContentParser;
-import org.elasticsearch.common.xcontent.json.JsonXContent;
-
 /**
  * Holds the specification used to turn {@code do} actions in the YAML suite into REST api calls.
  */
@@ -103,20 +104,25 @@ private static void parseSpecFile(ClientYamlSuiteRestApiParser restApiParser, Pa
                     while (parser.nextToken() != XContentParser.Token.END_OBJECT) {
                         if (parser.currentToken() == XContentParser.Token.FIELD_NAME) {
                             currentFieldName = parser.currentName();
-                        } else if (parser.currentToken() == XContentParser.Token.START_OBJECT
-                            && "params".equals(currentFieldName)) {
-                            while (parser.nextToken() == XContentParser.Token.FIELD_NAME) {
-                                String param = parser.currentName();
-                                if (restSpec.globalParameters.contains(param)) {
-                                    throw new IllegalArgumentException("Found duplicate global param [" + param + "]");
-                                }
-                                restSpec.globalParameters.add(param);
-                                parser.nextToken();
-                                if (parser.currentToken() != XContentParser.Token.START_OBJECT) {
-                                    throw new IllegalArgumentException("Expected params field in rest api definition to " +
-                                        "contain an object");
+                        } else if (parser.currentToken() == XContentParser.Token.START_OBJECT) {
+                            if ("params".equals(currentFieldName)) {
+                                while (parser.nextToken() == XContentParser.Token.FIELD_NAME) {
+                                    String param = parser.currentName();
+                                    if (restSpec.globalParameters.contains(param)) {
+                                        throw new IllegalArgumentException("Found duplicate global param [" + param + "]");
+                                    }
+                                    restSpec.globalParameters.add(param);
+                                    parser.nextToken();
+                                    if (parser.currentToken() != XContentParser.Token.START_OBJECT) {
+                                        throw new IllegalArgumentException("Expected params field in rest api definition to " +
+                                            "contain an object");
+                                    }
+                                    parser.skipChildren();
                                 }
+                            } else  if ("documentation".equals(currentFieldName)) {
                                 parser.skipChildren();
+                            } else {
+                                throw new ParsingException(parser.getTokenLocation(), "unsupported field [" + currentFieldName + "]");
                             }
                         }
                     }