doc: Document breaking changes for new UnmatchedFieldTypeModule Seria…

…lization defaults

CHANGELOG.md

@@ -17,7 +17,10 @@
 * Fix #3430: Support Vertical Pod Autoscaler
 
 #### _**Note**_: Breaking changes in the API
-
+##### Tools Changes:
+- Serialization: Those KubernetesResources that include entries in the additionalProperties Map that override a field
+  of the resource instance, will no longer be duplicated. The values present in the additionalProperties Map take
+  precedence.
 
 ### 5.9.0 (2021-10-14)
 

kubernetes-client/src/main/java/io/fabric8/kubernetes/client/utils/Serialization.java

@@ -60,14 +60,47 @@ private Serialization() { }
 
   private static final String DOCUMENT_DELIMITER = "---";
 
+  /**
+   * {@link ObjectMapper} singleton instance used internally by the Kubernetes client.
+   *
+   * <p> The ObjectMapper has an {@link UnmatchedFieldTypeModule} module registered. This module allows the client
+   * to work with Resources that contain properties that don't match the target field type. This is especially useful
+   * and necessary to work with OpenShift Templates.
+   *
+   * <p> n.b. the use of this module gives precedence to properties present in the additionalProperties Map present
+   * in most KubernetesResource instances. If a property is both defined in the Map and in the original field, the
+   * one from the additionalProperties Map will be serialized.
+   */
   public static ObjectMapper jsonMapper() {
     return JSON_MAPPER;
   }
 
+  /**
+   * {@link ObjectMapper} singleton instance used internally by the Kubernetes client.
+   *
+   * <p> The ObjectMapper has an {@link UnmatchedFieldTypeModule} module registered. This module allows the client
+   * to work with Resources that contain properties that don't match the target field type. This is especially useful
+   * and necessary to work with OpenShift Templates.
+   *
+   * <p> n.b. the use of this module gives precedence to properties present in the additionalProperties Map present
+   * in most KubernetesResource instances. If a property is both defined in the Map and in the original field, the
+   * one from the additionalProperties Map will be serialized.
+   */
   public static ObjectMapper yamlMapper() {
     return YAML_MAPPER;
   }
 
+  /**
+   * Returns a JSON representation of the given object.
+   *
+   * <p> If the provided object contains a JsonAnyGetter annotated method with a Map that contains an entry that
+   * overrides a field of the provided object, the Map entry will take precedence upon serialization. Properties won't
+   * be duplicated.
+   *
+   * @param object the object to serialize.
+   * @param <T> the type of the object being serialized.
+   * @return a String containing a JSON representation of the provided object.
+   */
   public static <T> String asJson(T object) {
     try {
       return JSON_MAPPER.writeValueAsString(object);
@@ -76,6 +109,17 @@ public static <T> String asJson(T object) {
     }
   }
 
+  /**
+   * Returns a YAML representation of the given object.
+   *
+   * <p> If the provided object contains a JsonAnyGetter annotated method with a Map that contains an entry that
+   * overrides a field of the provided object, the Map entry will take precedence upon serialization. Properties won't
+   * be duplicated.
+   *
+   * @param object the object to serialize.
+   * @param <T> the type of the object being serialized.
+   * @return a String containing a JSON representation of the provided object.
+   */
   public static <T> String asYaml(T object) {
     try {
       return YAML_MAPPER.writeValueAsString(object);