From 9601f7a9f39a48aca1ff13286fa298385847d160 Mon Sep 17 00:00:00 2001
From: Marc Nuri <marc@marcnuri.com>
Date: Tue, 9 Nov 2021 16:59:43 +0100
Subject: [PATCH] doc: Document breaking changes for new
 UnmatchedFieldTypeModule Serialization defaults

---
 CHANGELOG.md                                  |  5 ++-
 .../client/utils/Serialization.java           | 44 +++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fb9f3b94fe..52dfc7eba2c 100644
--- a/CHANGELOG.md
+++ b/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)
 
diff --git a/kubernetes-client/src/main/java/io/fabric8/kubernetes/client/utils/Serialization.java b/kubernetes-client/src/main/java/io/fabric8/kubernetes/client/utils/Serialization.java
index 75fe2325a13..5d59ff2ac9b 100644
--- a/kubernetes-client/src/main/java/io/fabric8/kubernetes/client/utils/Serialization.java
+++ b/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);