Update API REST specs to 7.2.0 (#3979)

* Update REST specs to 7.2.0
* Update ApiGenerator
- Add stability field
- Exclude new APIs
- Add XML comments for Beta / Experimental stability

Author: codebrain

src/CodeGeneration/ApiGenerator/Configuration/CodeConfiguration.cs

@@ -17,6 +17,15 @@ public static class CodeConfiguration
 
 			// these APIs are not ready for primetime yet
 			"rank_eval.json",
+			"data_frame.delete_data_frame_transform.json",
+			"data_frame.get_data_frame_transform.json",
+			"data_frame.get_data_frame_transform_stats.json",
+			"data_frame.preview_data_frame_transform.json",
+			"data_frame.put_data_frame_transform.json",
+			"data_frame.start_data_frame_transform.json",
+			"data_frame.stop_data_frame_transform.json",
+
+			"scripts_painless_context.json",
 
 			// these APIs are new and need to be mapped
 			"ml.set_upgrade_mode.json",

src/CodeGeneration/ApiGenerator/Domain/Code/HighLevel/Requests/RequestPartialImplementation.cs

@@ -2,12 +2,13 @@
 using ApiGenerator.Configuration;
 using ApiGenerator.Domain.Specification;
 
-namespace ApiGenerator.Domain.Code.HighLevel.Requests 
+namespace ApiGenerator.Domain.Code.HighLevel.Requests
 {
 	public class RequestPartialImplementation
 	{
 		public CsharpNames CsharpNames { get; set; }
 		public string OfficialDocumentationLink { get; set; }
+		public Stability Stability { get; set; }
 		public IReadOnlyCollection<UrlPart> Parts { get; set; }
 		public IReadOnlyCollection<UrlPath> Paths { get; set; }
 		public IReadOnlyCollection<QueryParameters> Params { get; set; }
@@ -20,7 +21,7 @@ public class RequestPartialImplementation
 		public bool NeedsGenericImplementation => !GenerateOnlyGenericInterface && !string.IsNullOrWhiteSpace(CsharpNames.GenericsDeclaredOnRequest);
 
 		public string Name => CsharpNames.GenericOrNonGenericRequestPreference;
-		
+
 		public string InterfaceName => CsharpNames.GenericOrNonGenericInterfacePreference;
 	}
-}
+}

src/CodeGeneration/ApiGenerator/Domain/Code/LowLevel/LowLevelClientMethod.cs

@@ -11,6 +11,8 @@ public class LowLevelClientMethod
 
 		public string Arguments { get; set; }
 		public string OfficialDocumentationLink { get; set; }
+
+		public Stability Stability { get; set; }
 		public string PerPathMethodName { get; set; }
 		public string HttpMethod { get; set; }
 

src/CodeGeneration/ApiGenerator/Domain/Specification/ApiEndpoint.cs

@@ -6,36 +6,41 @@
 using ApiGenerator.Domain.Code.HighLevel.Requests;
 using ApiGenerator.Domain.Code.LowLevel;
 using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
 
 namespace ApiGenerator.Domain.Specification
 {
 	public class ApiEndpoint
 	{
 		/// <summary> The filename of the spec describing the api endpoint </summary>
 		public string FileName { get; set; }
-		
+
 		/// <summary> The original name as declared in the spec </summary>
 		public string Name { get; set; }
-		
+
 		/// <summary> The original namespace as declared in the spec </summary>
 		public string Namespace { get; set; }
-		
+
 		/// <summary> The original method name as declared in the spec </summary>
 		public string MethodName { get; set; }
-		
+
 		/// <summary> Computed Csharp identifier names </summary>
-		public CsharpNames CsharpNames { get; set; } 
-		
+		public CsharpNames CsharpNames { get; set; }
+
+		[JsonConverter(typeof(StringEnumConverter))]
+		[JsonProperty("stability")]
+		public Stability Stability { get; set; }
+
 		[JsonProperty("documentation")]
 		public string OfficialDocumentationLink { get; set; }
-		
+
 		public UrlInformation Url { get; set; }
-		
+
 		public Body Body { get; set; }
 
 		[JsonProperty("methods")]
 		public IReadOnlyCollection<string> HttpMethods { get; set; }
-		
+
 		public IEndpointOverrides Overrides { get; internal set; }
 
 		public RequestInterface RequestInterface => new RequestInterface
@@ -45,30 +50,31 @@ public class ApiEndpoint
 			PartialParameters = Body == null ? Enumerable.Empty<QueryParameters>().ToList() : Url.Params.Values.Where(p=>p.RenderPartial && !p.Skip).ToList(),
 			OfficialDocumentationLink = OfficialDocumentationLink
 		};
-		
+
 		public RequestPartialImplementation RequestPartialImplementation => new RequestPartialImplementation
 		{
 			CsharpNames = CsharpNames,
 			OfficialDocumentationLink = OfficialDocumentationLink,
+			Stability = Stability,
 			Paths = Url.Paths,
 			Parts = Url.Parts,
 			Params = Url.Params.Values.Where(p=>!p.Skip).ToList(),
 			Constructors = Constructor.RequestConstructors(CsharpNames, Url, inheritsFromPlainRequestBase: true).ToList(),
 			GenericConstructors = Constructor.RequestConstructors(CsharpNames, Url, inheritsFromPlainRequestBase: false).ToList(),
 			HasBody = Body != null,
 		};
-		
+
 		public DescriptorPartialImplementation DescriptorPartialImplementation => new DescriptorPartialImplementation
 		{
-			CsharpNames = CsharpNames, 
+			CsharpNames = CsharpNames,
 			OfficialDocumentationLink = OfficialDocumentationLink,
 			Constructors = Constructor.DescriptorConstructors(CsharpNames, Url).ToList(),
 			Paths = Url.Paths,
 			Parts = Url.Parts,
 			Params = Url.Params.Values.Where(p=>!p.Skip).ToList(),
 			HasBody = Body != null,
 		};
-		
+
 		public RequestParameterImplementation RequestParameterImplementation => new RequestParameterImplementation
 		{
 			CsharpNames = CsharpNames,
@@ -89,7 +95,7 @@ public string PreferredHttpMethod
 		}
 
 		public string HighLevelMethodXmlDocDescription => $"<c>{PreferredHttpMethod}</c> request to the <c>{Name}</c> API, read more about this API online:";
-		
+
 		public HighLevelModel HighLevelModel => new HighLevelModel
 		{
 			CsharpNames = CsharpNames,
@@ -132,15 +138,16 @@ public IReadOnlyCollection<LowLevelClientMethod> LowLevelClientMethods
 						.Select(p => p.Argument)
 						.Concat(new[] { CsharpNames.ParametersName + " requestParameters = null" })
 						.ToList();
-					
+
 					var apiMethod = new LowLevelClientMethod
 					{
 						Arguments = string.Join(", ", args),
 						CsharpNames = CsharpNames,
 						PerPathMethodName = methodName,
 						HttpMethod = httpMethod,
 						OfficialDocumentationLink = OfficialDocumentationLink,
-						DeprecatedPath = path.Deprecation, 
+						Stability = Stability,
+						DeprecatedPath = path.Deprecation,
 						Path = path.Path,
 						Parts = parts,
 						Url = Url,

src/CodeGeneration/ApiGenerator/Domain/Specification/Stability.cs

@@ -0,0 +1,25 @@
+using System.Runtime.Serialization;
+
+namespace ApiGenerator.Domain.Specification
+{
+	public enum Stability
+	{
+		/// <summary>
+		/// Highly likely to break in the near future (minor/path), no BWC guarantees. Possibly removed in the future.
+		/// </summary>
+		[EnumMember(Value = "experimental")]
+		Experimental,
+
+		/// <summary>
+		/// Less likely to break or be removed but still reserve the right to do so.
+		/// </summary>
+		[EnumMember(Value = "beta")]
+		Beta,
+
+		/// <summary>
+		/// No backwards breaking changes in a minor.
+		/// </summary>
+		[EnumMember(Value = "stable")]
+		Stable
+	}
+}

src/CodeGeneration/ApiGenerator/Generator/ApiGenerator.cs

@@ -48,6 +48,15 @@ public static async Task Generate(string downloadBranch, params string[] folders
 				}
 			}
 
+			// Check if there are any non-Stable endpoints present.
+			foreach (var endpoint in spec.Endpoints)
+			{
+				if (endpoint.Value.Stability != Stability.Stable)
+				{
+					Warnings.Add($"Endpoint {endpoint.Value.Name} is not marked as Stable ({endpoint.Value.Stability})");
+				}
+			}
+
 			if (Warnings.Count == 0) return;
 
 			Console.ForegroundColor = ConsoleColor.Yellow;
@@ -106,7 +115,6 @@ private static RestApiSpec CreateRestApiSpecModel(string downloadBranch, string[
 				var isIgnored = CodeConfiguration.IgnoredApis.Contains($"{value}.json");
 				if (isIgnored) Warnings.Add($"{value} uses MapsApi: {key} ignored in ${nameof(CodeConfiguration)}.{nameof(CodeConfiguration.IgnoredApis)}");
 				else Warnings.Add($"{value} uses MapsApi: {key} which does not exist");
-
 			}
 
 			return new RestApiSpec { Endpoints = endpoints, Commit = downloadBranch };
@@ -119,7 +127,5 @@ private static SortedDictionary<string, QueryParameters> CreateCommonApiQueryPar
 			var commonParameters = jobject.Property("params").Value.ToObject<Dictionary<string, QueryParameters>>();
 			return ApiQueryParametersPatcher.Patch(null, commonParameters, null, false);
 		}
-
-
 	}
 }

src/CodeGeneration/ApiGenerator/Generator/CodeGenerator.cs

@@ -44,7 +44,6 @@ void A(string s)
 			}
 		}
 
-
 		private static IEnumerable<string> RenderDocumentation(params string[] doc)
 		{
 			doc = (doc?.SelectMany(WrapDocumentation) ?? Enumerable.Empty<string>()).ToArray();

src/CodeGeneration/ApiGenerator/RestSpecification/Core/bulk.json

@@ -1,9 +1,9 @@
 {
   "bulk": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html",
+    "stability": "stable",
     "methods": ["POST", "PUT"],
     "url": {
-      "path": "/_bulk",
       "paths": ["/_bulk", "/{index}/_bulk", "/{index}/{type}/_bulk"],
       "parts": {
         "index": {

src/CodeGeneration/ApiGenerator/RestSpecification/Core/cat.aliases.json

@@ -1,9 +1,9 @@
 {
   "cat.aliases": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-alias.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
-      "path": "/_cat/aliases",
       "paths": ["/_cat/aliases", "/_cat/aliases/{name}"],
       "parts": {
         "name": {

src/CodeGeneration/ApiGenerator/RestSpecification/Core/cat.allocation.json

@@ -1,9 +1,9 @@
 {
   "cat.allocation": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-allocation.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
-      "path": "/_cat/allocation",
       "paths": ["/_cat/allocation", "/_cat/allocation/{node_id}"],
       "parts": {
         "node_id": {