Add docs about MissingRequiredPropertyException (#301) (#302)

Co-authored-by: Sylvain Wallez <sylvain@elastic.co>

docs/api-conventions/exceptions.asciidoc

@@ -1,4 +1,4 @@
-[[exceptions]]
+[[exception-conventions]]
 === Exceptions
 
 Client methods can throw two kinds of exceptions:

docs/api-conventions/index.asciidoc

@@ -15,7 +15,7 @@ to process. The sections below explain these in details.
 ifdef::is_main_branch,v8_1_1_released,v7_17_2_released[]
 * <<loading-json>>
 endif::is_main_branch,v8_1_1_released,v7_17_2_released[]
-* <<exceptions>>
+* <<exception-conventions>>
 
 include::package-structure.asciidoc[]
 include::method-naming.asciidoc[]

docs/index.asciidoc

@@ -32,7 +32,7 @@ include::api-conventions/index.asciidoc[]
 
 include::usage/index.asciidoc[]
 
-// include::troubleshooting/index.asciidoc[]
+include::troubleshooting/index.asciidoc[]
 include::javadoc-and-source.asciidoc[]
 include::release-notes/index.asciidoc[]
 include::external-resources.asciidoc[]

docs/troubleshooting/index.asciidoc

@@ -1,13 +1,18 @@
+[[troubleshooting]]
 == Troubleshooting
 
-=== Understanding exceptions
+// * <<debugging>>
+// * <<deprecation-warnings>>
 
-TBD
+.Exceptions
 
-=== Debugging
+* <<missing-required-property>>
 
-TBD
 
-=== Elasticsearch deprecation warnings
+// [[debugging]]
+// === Debugging
 
-TBD
+//[[deprecation-warnings]]
+// === Elasticsearch deprecation warnings
+
+include::missing-required-property.asciidoc[]

docs/troubleshooting/missing-required-property.asciidoc

@@ -0,0 +1,38 @@
+[[missing-required-property]]
+=== `MissingRequiredPropertyException` in a response
+
+The {java-client} distinguishes optional and required properties. Optional properties are marked with the `@Nullable` annotation.
+
+When an API object is built and a required property hasn't been set, a `MissingRequiredPropertyException` is thrown. This applies both to request object built by your application and to response objects returned by Elasticsearch, so that you can be assured that a property that does not have the `@Nullable` annotation will never be `null`.
+
+However, there may be bugs in the https://github.com/elastic/elasticsearch-specification[Elasticsearch API specification] where a response object's property is incorrectly required, leading to a `MissingRequiredPropertyException` when deserializing a response. If this happens, here's how you can work around it:
+
+* Make sure you use the latest release of the {java-client}. The issue may already have been fixed.
+* If the issue is still present on the latest version, https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that we can fix it in the next release. Please help us to improve the {java-client}.
+* Temporarily disable required property checks for the offending request:
+
+WARNING: This is a workaround. Do not consider this as a permanent solution, and please https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that the problem can be fixed in a future release.
+
+["source","java"]
+--------------------------------------------------
+    ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true);
+    SomeRequest request = SomeRequest.of(...);
+    SomeResponse response = esClient.someApi(request);
+    ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(false);
+    // Do something with response
+}
+--------------------------------------------------
+
+The `DANGEROUS_disableRequiredPropertiesCheck` method disables required property checks on the current thread, and for response deserialization in asynchronous requests. As its name implies, it is dangerous as it removes the guarantees of properties that are not `@Nullable`. This is a temporary workaround until the issue is fixed.
+
+Note that the result of this method is an `AutoCloseable` object that resets required property checks to its previous setting. You can therefore use it in a try-with-resource block as follows:
+
+["source","java"]
+--------------------------------------------------
+try (ApiTypeHelper.DisabledChecksHandle h =
+        ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true)) {
+    SomeRequest request = SomeRequest.of(...);
+    SomeResponse response = esClient.someApi(request);
+    // Do something with response
+}
+--------------------------------------------------

docs/usage/aggregations.asciidoc

@@ -3,7 +3,7 @@
 
 An aggregation summarizes your data as metrics, statistics, or other analytics.
 
-NOTE: See the es-docs}/search-aggregations[{es} documentation] for a full explanation of aggregations.
+NOTE: See the {es-docs}/search-aggregations.html[{es} documentation] for a full explanation of aggregations.
 
 [discrete]
 ==== A simple aggregation