[Java] Configuration option to disable HTML escaping when using Gson

[stianlik]

PR checklist

• Read the contribution guidelines.
• Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
• Filed the PR against the correct branch: 3.0.0 branch for changes related to OpenAPI spec 3.0. Default: master.
• Copied the technical committee to review the pull request if your PR is targeting a particular programming language. @bbdouglas (2017/07) @JFCote (2017/08) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01)

Description of the PR

The default implementation of Gson will escape certain characters. This includes the = character, which is used in base64 encoding and cause problems when deserializing the value to a base64 encoded string in a service.

Adding an option for disabling this feature makes it easier to generate client code with sane defaults.

[jeff9finger]

I'd like to see more documentation describing the need and what is done. It takes some looking around to figure it out.

[stianlik]

This is a small change, but generating the Petstore example created a large diff. To see what this PR contains, it's easiest to view the relevant commit directly.

What do this PR include

A new option -DdisableHtmlEscaping=true, that can be used when generating Java-code using Gson in order to disable escaping of string values. Mainly to avoid escaping the = character when working with base64-encoded data. The option is documented as a configuration property (swagger-gen config-help -l java).

Why is this needed

When base64 support was implemented, the author initially disabled the Gson default for strings, which is to escape characters that could cause problems in an XML document. He did this because the escape feature caused problems with the = character, and resulted in invalid base64 code. I considered marking this as a bug, and implementing the fix without an option as per the original PR, but I chose to regard it as a feature request instead since it seemed like the preferred option was to keep the defaults for Gson. This preserves backwards compability and allow users to override the default setting instead of changing the existing behavior.

According to RFC 4648, base64 use a limited character subset, in addition to the = character.

A 65-character subset of US-ASCII is used, enabling 6 bits to be represented per printable character. (The extra 65th character, "=", is used to signify a special processing function.)

This means that ABC== is a valid base64 encoded string. However, the default behavior for Gson is to accommodate XML output by escaping certain characters, so we end up with ABC\u003d\u003d, which is not a valid base64 string, unless the receiver first unescape the = character.

I encountered this problem when I integrated with a service that accepts base64, processed through Spring and Jackson. When we send base64 data to the service, it works just fine. However, when the = signs are escaped, we (correctly) get a mapping error. I temporarily resolved the issue by modifying the generated client code and adding builder.disableHtmlEscaping() to disable this behavior. This works, for now, but we have to modify the generated code every time we make a change to the service. Instead, it would be very helpful to have an option to disable this behavior when we generate the code, which is what this PR provides.

[stianlik]

@jeff9finger Do you need anything more to review the pull request?

[jeff9finger]

Great explanation and documentation!
LGTM 👍

[jeff9finger]

👍

[stianlik]

@HugoMario Any possibility for merging this?

[HugoMario]

yes, sorry for delay, thanks!!