update _common.json format (#46872)

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

Co-Authored-By: Tomas Della Vedova <delvedor@users.noreply.github.com>

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" : {
-  "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html",
+    "description": "Parameters that are accepted by all API endpoints.",
+    "url": "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,12 @@
  */
 package org.elasticsearch.test.rest.yaml.restspec;
 
+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 +36,6 @@ import java.util.Map;
 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.
  */
@@ -43,7 +43,7 @@ public class ClientYamlSuiteRestSpec {
     private final Set<String> globalParameters = new HashSet<>();
     private final Map<String, ClientYamlSuiteRestApi> restApiMap = new HashMap<>();
 
-    private ClientYamlSuiteRestSpec() {}
+    ClientYamlSuiteRestSpec() {}
 
     private void addApi(ClientYamlSuiteRestApi restApi) {
         ClientYamlSuiteRestApi previous = restApiMap.putIfAbsent(restApi.getName(), restApi);
@@ -99,27 +99,7 @@ public class ClientYamlSuiteRestSpec {
                      JsonXContent.jsonXContent.createParser(NamedXContentRegistry.EMPTY, LoggingDeprecationHandler.INSTANCE, stream)) {
                 String filename = jsonFile.getFileName().toString();
                 if (filename.equals("_common.json")) {
-                    String currentFieldName = null;
+                    parseCommonSpec(parser, restSpec);
-                    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");
-                                }
-                                parser.skipChildren();
-                            }
-                        }
-                    }
                 } else {
                     ClientYamlSuiteRestApi restApi = restApiParser.parse(jsonFile.toString(), parser);
                     String expectedApiName = filename.substring(0, filename.lastIndexOf('.'));
@@ -134,4 +114,34 @@ public class ClientYamlSuiteRestSpec {
             throw new UncheckedIOException("Can't parse rest spec file: [" + jsonFile + "]", ex);
         }
     }
+
+    static void parseCommonSpec(XContentParser parser, ClientYamlSuiteRestSpec restSpec) throws IOException {
+        String currentFieldName = null;
+        parser.nextToken();
+        assert parser.currentToken() == XContentParser.Token.START_OBJECT;
+        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) {
+                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 {
+                    parser.skipChildren();
+                }
+            }
+        }
+
+    }
 }

test/framework/src/test/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestApiTests.java

@@ -29,6 +29,18 @@ import java.util.List;
 
 public class ClientYamlSuiteRestApiTests extends ESTestCase {
 
+    public void testParseCommonSpec() throws IOException {
+        XContentParser parser = createParser(YamlXContent.yamlXContent, COMMON_SPEC);
+        ClientYamlSuiteRestSpec restSpec = new ClientYamlSuiteRestSpec();
+        ClientYamlSuiteRestSpec.parseCommonSpec(parser, restSpec);
+        assertTrue(restSpec.isGlobalParameter("pretty"));
+        assertTrue(restSpec.isGlobalParameter("human"));
+        assertTrue(restSpec.isGlobalParameter("error_trace"));
+        assertTrue(restSpec.isGlobalParameter("source"));
+        assertTrue(restSpec.isGlobalParameter("filter_path"));
+        assertFalse(restSpec.isGlobalParameter("unknown"));
+    }
+
     public void testPathMatching() throws IOException {
         XContentParser parser = createParser(YamlXContent.yamlXContent, REST_SPEC_API);
         ClientYamlSuiteRestApi restApi = new ClientYamlSuiteRestApiParser().parse("index.json", parser);
@@ -66,6 +78,39 @@ public class ClientYamlSuiteRestApiTests extends ESTestCase {
         }
     }
 
+    private static final String COMMON_SPEC = "{\n"+
+        "  \"documentation\" : {\n"+
+        "    \"url\": \"Parameters that are accepted by all API endpoints.\",\n"+
+        "    \"documentation\": \"https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html\"\n"+
+        "  },\n"+
+        "  \"params\": {\n"+
+        "    \"pretty\": {\n"+
+        "      \"type\": \"boolean\",\n"+
+        "      \"description\": \"Pretty format the returned JSON response.\",\n"+
+        "      \"default\": false\n"+
+        "    },\n"+
+        "    \"human\": {\n"+
+        "      \"type\": \"boolean\",\n"+
+        "      \"description\": \"Return human readable values for statistics.\",\n"+
+        "      \"default\": true\n"+
+        "    },\n"+
+        "    \"error_trace\": {\n"+
+        "      \"type\": \"boolean\",\n"+
+        "      \"description\": \"Include the stack trace of returned errors.\",\n"+
+        "      \"default\": false\n"+
+        "    },\n"+
+        "    \"source\": {\n"+
+        "      \"type\": \"string\",\n"+
+        "      \"description\": \"The URL-encoded request definition." +
+        " Useful for libraries that do not accept a request body for non-POST requests.\"\n"+
+        "    },\n"+
+        "    \"filter_path\": {\n"+
+        "      \"type\": \"list\",\n"+
+        "      \"description\": \"A comma-separated list of filters used to reduce the response.\"\n"+
+        "    }\n"+
+        "  }\n"+
+        "}\n";
+
     private static final String REST_SPEC_API = "{\n" +
         "  \"index\":{\n" +
         "    \"documentation\":{\n" +