Document why "charset=UTF-8" is specified for JSON

Issue: SPR-14715

Author: sdeleuze

spring-web/src/main/java/org/springframework/http/MediaType.java

@@ -96,11 +96,23 @@ public class MediaType extends MimeType implements Serializable {
 
 	/**
 	 * Public constant media type for {@code application/json;charset=UTF-8}.
+	 *
+	 * <p>This {@link MediaType#APPLICATION_JSON} variant should be used to set JSON
+	 * content type because while
+	 * <a href="https://tools.ietf.org/html/rfc7159#section-11">RFC7159</a>
+	 * clearly states that "no charset parameter is defined for this registration", some
+	 * browsers require it for interpreting correctly UTF-8 special characters.
 	 */
 	public static final MediaType APPLICATION_JSON_UTF8;
 
 	/**
 	 * A String equivalent of {@link MediaType#APPLICATION_JSON_UTF8}.
+	 *
+	 * <p>This {@link MediaType#APPLICATION_JSON_VALUE} variant should be used to set JSON
+	 * content type because while
+	 * <a href="https://tools.ietf.org/html/rfc7159#section-11">RFC7159</a>
+	 * clearly states that "no charset parameter is defined for this registration", some
+	 * browsers require it for interpreting correctly UTF-8 special characters.
 	 */
 	public static final String APPLICATION_JSON_UTF8_VALUE = "application/json;charset=UTF-8";
 

spring-web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java

@@ -193,10 +193,10 @@
 	 * <pre class="code">
 	 * produces = "text/plain"
 	 * produces = {"text/plain", "application/*"}
-	 * produces = "application/json; charset=UTF-8"
+	 * produces = MediaType.APPLICATION_JSON_UTF8_VALUE
 	 * </pre>
 	 * <p>It affects the actual content type written, for example to produce a JSON response
-	 * with UTF-8 encoding, {@code "application/json; charset=UTF-8"} should be used.
+	 * with UTF-8 encoding, {@link org.springframework.http.MediaType#APPLICATION_JSON_UTF8_VALUE} should be used.
 	 * <p>Expressions can be negated by using the "!" operator, as in "!text/plain", which matches
 	 * all requests with a {@code Accept} other than "text/plain".
 	 * <p><b>Supported at the type level as well as at the method level!</b>

src/docs/asciidoc/web/webflux.adoc

@@ -1192,7 +1192,7 @@ overrides rather than extend the class level declaration.
 [TIP]
 ====
 `MediaType` provides constants for commonly used media types -- e.g.
-`APPLICATION_JSON_VALUE`, `APPLICATION_JSON_UTF8_VALUE`.
+`APPLICATION_JSON_VALUE`, `APPLICATION_XML_VALUE`.
 ====
 
 
@@ -1216,14 +1216,22 @@ content types that a controller method produces:
 The media type can specify a character set. Negated expressions are supported -- e.g.
 `!text/plain` means any content type other than "text/plain".
 
+[NOTE]
+====
+For JSON content type, the UTF-8 charset should be specified even if
+https://tools.ietf.org/html/rfc7159#section-11[RFC7159]
+clearly states that "no charset parameter is defined for this registration" because some
+browsers require it for interpreting correctly UTF-8 special characters.
+====
+
 You can declare a shared produces attribute at the class level. Unlike most other request
 mapping attributes however when used at the class level, a method-level produces attribute
 overrides rather than extend the class level declaration.
 
 [TIP]
 ====
 `MediaType` provides constants for commonly used media types -- e.g.
-`APPLICATION_JSON_VALUE`, `APPLICATION_JSON_UTF8_VALUE`.
+`APPLICATION_JSON_UTF8_VALUE`, `APPLICATION_XML_VALUE`.
 ====
 
 

src/docs/asciidoc/web/webmvc.adoc

@@ -1425,7 +1425,7 @@ will overrides rather than extend the class level declaration.
 [TIP]
 ====
 `MediaType` provides constants for commonly used media types -- e.g.
-`APPLICATION_JSON_VALUE`, `APPLICATION_JSON_UTF8_VALUE`.
+`APPLICATION_JSON_VALUE`, `APPLICATION_XML_VALUE`.
 ====
 
 
@@ -1449,14 +1449,22 @@ content types that a controller method produces:
 The media type can specify a character set. Negated expressions are supported -- e.g.
 `!text/plain` means any content type other than "text/plain".
 
+[NOTE]
+====
+For JSON content type, the UTF-8 charset should be specified even if
+https://tools.ietf.org/html/rfc7159#section-11[RFC7159]
+clearly states that "no charset parameter is defined for this registration" because some
+browsers require it for interpreting correctly UTF-8 special characters.
+====
+
 You can declare a shared produces attribute at the class level. Unlike most other request
 mapping attributes however when used at the class level, a method-level produces attribute
 will overrides rather than extend the class level declaration.
 
 [TIP]
 ====
 `MediaType` provides constants for commonly used media types -- e.g.
-`APPLICATION_JSON_VALUE`, `APPLICATION_JSON_UTF8_VALUE`.
+`APPLICATION_JSON_UTF8_VALUE`, `APPLICATION_XML_VALUE`.
 ====