[Java][okhttp-gson] Add option to employ builders for API requests

[Kiran-Sivakumar]

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: master, 3.4.x, 4.0.x. Default: master.
• Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

@bbdouglas @JFCote @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger

Description of the PR

fix #1217
This PR (filed against branch 3.4.x) adds the option to generate APIs of the form shown in the proposed solution in the above issue. This makes generated okhttp-gson clients much nicer to use, especially in cases involving unused optional parameters. The hope is to implement a similar solution for all Java generators in the future, so that generated Java clients aren't frustrating to use.

Changes:

• JavaClientCodegen.java modified to add a new CLI option "useBuildersForApiRequests" (default: false)
• okhttp-gson/api.mustache
  • Optionally generate API-request builders
  • Change original methods from "public" to "private" if builders are generated, since user will want to use the public builder methods instead (the builder methods simply wrap around the original methods that take all parameters as input)
  • Generate comments
• okhttp-gson/api_test.mustache added to generate tests that use the builders if the "useBuildersForApiRequests" option is enabled
• bin/java-petstore-okhttp-gson-builders.sh added to generate petstore samples with API-request builders (added one for Windows as well)
• samples/client/petstore/java/okhttp-gson-requestBuilders/: new petstore samples generated with the above script
• docs/generators/java.md updated with new config option

I also ran the original shell scripts under ./bin/ to ensure that absolutely nothing changes in the existing petstore samples when the "useBuildersForApiRequests" option is disabled.

[cbornet]

I would set it to true by default

[cbornet]

Too many options 😢

[cbornet]

As always, I'm reluctant to have too many options. So I would prefer to always generate the builder, keep the constructors public and have a way to encourage users to move to the builder style (eg. setting the constructor @Deprecated and adding a comment that future version will set it as private. Then in a minor release or 2, we can completely switch to private.

[Kiran-Sivakumar]

@cbornet Thanks for your feedback. I agree that too many options can be undesirable. Perhaps the option can be removed in the next major release (to only generate the builder style)? Otherwise, I can incorporate your proposed changes. This would require the public builder method name to be changed, however, to not conflict with one of the current method names.

[wing328]

@Kiran-Sivakumar @cbornet FYI. next major version 4.x (with breaking changes) will be released before year-end so we can clean up the options as part of the 4.x release later.

[Kiran-Sivakumar]

Ok, so should I keep it as an option for this PR, changing it to be true by default, and file another PR against 4.x in a few weeks that removes the option entirely?

[wing328]

@Kiran-Sivakumar I've other ideas. Let me review and get back to you by Thursday.

[wing328]

@Kiran-Sivakumar instead of using useBuildersForApiRequests in the templates, what about using x-group-parameters vendor extensions like what I did for PHP in https://github.com/OpenAPITools/openapi-generator/pull/1337/files#diff-076573ccfdac2ab5af4dc1813e5ccee3R92?

This will avoid another option and make it possible to enable group parameters per operation.

[Kiran-Sivakumar]

I see. What if you wanted to enable builders for all operations for a cohesive API? Is there an easy way to apply group parameters to all of them?

[wing328]

@Kiran-Sivakumar similar to what we did for consumes, produces (global vs local), if x-group-parameters is defined in the top level of the spec, we will add x-group-parameters to all operations in postProcessOperationsAndModel (only if x-group-parameters is not defined in the operation level).

Does it sound good to you?

[Kiran-Sivakumar]

Oh great. Yes, this sounds good to me. I'll incorporate your feedback.

[wing328]

@Kiran-Sivakumar I've filed #1405 to add top level x-group-parameters support.

[Kiran-Sivakumar]

@cbornet @wing328 I have incorporated your feedback.

[wing328]

@Kiran-Sivakumar thanks for the PR, which has been included in the v3.3.4 release: https://twitter.com/oas_generator/status/1068772409795207168