From 0b0d19c9cffac7372e043892232b64044069db25 Mon Sep 17 00:00:00 2001 From: Russ Cam Date: Mon, 27 Aug 2018 13:13:07 +1000 Subject: [PATCH] Add note about filter_path and deserialization This commit adds a note to the filter_path XML comments to warn about response filtering potentially affecting deserialization to the respective response type. Include XML comments on common options for Descriptor types Closes #3331 --- .../ApiGenerator/Domain/ApiQueryParameters.cs | 6 ++++++ .../ApiGenerator/RestSpecification/Core/_common.json | 2 +- .../ApiGenerator/Views/_Descriptors.Generated.cshtml | 5 +++-- src/Nest/CommonAbstractions/Request/RequestBase.cs | 3 +++ src/Nest/_Generated/_Descriptors.generated.cs | 12 ++++++++---- src/Nest/_Generated/_Requests.generated.cs | 7 ++++++- 6 files changed, 27 insertions(+), 8 deletions(-) diff --git a/src/CodeGeneration/ApiGenerator/Domain/ApiQueryParameters.cs b/src/CodeGeneration/ApiGenerator/Domain/ApiQueryParameters.cs index 3ca2a77f0fc..ad45d5e6ca9 100644 --- a/src/CodeGeneration/ApiGenerator/Domain/ApiQueryParameters.cs +++ b/src/CodeGeneration/ApiGenerator/Domain/ApiQueryParameters.cs @@ -101,6 +101,12 @@ public IEnumerable DescriptionHighLevel case "_source": yield return "Whether the _source should be included in the response."; yield break; + case "filter_path": + yield return this.Description; + yield return "Use of response filtering can result in a response from Elasticsearch "; + yield return "that cannot be correctly deserialized to the respective response type for the request. "; + yield return "In such situations, use the low level client to issue the request and handle response deserialization"; + yield break; default: yield return this.Description; yield break; diff --git a/src/CodeGeneration/ApiGenerator/RestSpecification/Core/_common.json b/src/CodeGeneration/ApiGenerator/RestSpecification/Core/_common.json index 6edd6d80320..69a1f8fb8ce 100644 --- a/src/CodeGeneration/ApiGenerator/RestSpecification/Core/_common.json +++ b/src/CodeGeneration/ApiGenerator/RestSpecification/Core/_common.json @@ -23,7 +23,7 @@ }, "filter_path": { "type": "list", - "description": "A comma-separated list of filters used to reduce the respone." + "description": "A comma-separated list of filters used to reduce the response." } } } diff --git a/src/CodeGeneration/ApiGenerator/Views/_Descriptors.Generated.cshtml b/src/CodeGeneration/ApiGenerator/Views/_Descriptors.Generated.cshtml index 27ded8c83fb..64d22bf6d2a 100644 --- a/src/CodeGeneration/ApiGenerator/Views/_Descriptors.Generated.cshtml +++ b/src/CodeGeneration/ApiGenerator/Views/_Descriptors.Generated.cshtml @@ -24,8 +24,9 @@ namespace Nest var original = common.QueryStringKey; var t = @common.TypeHighLevel; var tSuffix = (t == "bool" || t == "bool?") ? " = true" : ""; - public TDescriptor @(common.ClsName)(@common.TypeHighLevel @common.ClsArgumentName@tSuffix) => Qs("@original", @(common.ClsArgumentName)); - + ///@(Raw(string.Join("", common.DescriptionHighLevel))) + public TDescriptor @(common.ClsName)(@common.TypeHighLevel @common.ClsArgumentName@tSuffix) => Qs("@original", @(common.ClsArgumentName)); + } } @foreach (CsharpMethod method in Model.CsharpMethodsWithQueryStringInfo) diff --git a/src/Nest/CommonAbstractions/Request/RequestBase.cs b/src/Nest/CommonAbstractions/Request/RequestBase.cs index 7f84a6349f4..182f8d21c2d 100644 --- a/src/Nest/CommonAbstractions/Request/RequestBase.cs +++ b/src/Nest/CommonAbstractions/Request/RequestBase.cs @@ -81,6 +81,9 @@ public IRequestConfiguration RequestConfiguration } } + /// + /// Base class for all Request descriptor types + /// public abstract partial class RequestDescriptorBase : RequestBase, IDescriptor where TDescriptor : RequestDescriptorBase, TInterface where TParameters : RequestParameters, new() diff --git a/src/Nest/_Generated/_Descriptors.generated.cs b/src/Nest/_Generated/_Descriptors.generated.cs index ec2071c93c2..8896a3c80e8 100644 --- a/src/Nest/_Generated/_Descriptors.generated.cs +++ b/src/Nest/_Generated/_Descriptors.generated.cs @@ -12,11 +12,15 @@ namespace Nest { public abstract partial class RequestDescriptorBase { + ///Pretty format the returned JSON response. public TDescriptor Pretty(bool? pretty = true) => Qs("pretty", pretty); - public TDescriptor Human(bool? human = true) => Qs("human", human); - public TDescriptor ErrorTrace(bool? errorTrace = true) => Qs("error_trace", errorTrace); - public TDescriptor FilterPath(string[] filterPath) => Qs("filter_path", filterPath); - } + ///Return human readable values for statistics. + public TDescriptor Human(bool? human = true) => Qs("human", human); + ///Include the stack trace of returned errors. + public TDescriptor ErrorTrace(bool? errorTrace = true) => Qs("error_trace", errorTrace); + ///A comma-separated list of filters used to reduce the response.Use of response filtering can result in a response from Elasticsearch that cannot be correctly deserialized to the respective response type for the request. In such situations, use the low level client to issue the request and handle response deserialization + public TDescriptor FilterPath(string[] filterPath) => Qs("filter_path", filterPath); + } ///descriptor for Bulk 
http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html
 public partial class BulkDescriptor : RequestDescriptorBase, IBulkRequest diff --git a/src/Nest/_Generated/_Requests.generated.cs b/src/Nest/_Generated/_Requests.generated.cs index 322ea97f872..14c9ac46755 100644 --- a/src/Nest/_Generated/_Requests.generated.cs +++ b/src/Nest/_Generated/_Requests.generated.cs @@ -20,7 +20,12 @@ public abstract partial class PlainRequestBase public bool? Human { get => Q("human"); set => Q("human", value); } ///Include the stack trace of returned errors. public bool? ErrorTrace { get => Q("error_trace"); set => Q("error_trace", value); } - ///A comma-separated list of filters used to reduce the respone. + /// + /// A comma-separated list of filters used to reduce the response. + /// Use of response filtering can result in a response from Elasticsearch + /// that cannot be correctly deserialized to the respective response type for the request. + /// In such situations, use the low level client to issue the request and handle response deserialization + /// public string[] FilterPath { get => Q("filter_path"); set => Q("filter_path", value); } }