[JAVA] Support using the builder pattern for API calls

Description

In the Java API generator, all query parameters for an operation -- including optional parameters -- are added to the corresponding method.

For example, this is the method definition produced by the sample specification provided below:

public String getItem(String requiredParam1, String requiredParam2, String optionalParam1, String optionalParam2, String optionalParam3) throws ApiException { ... }

This makes it difficult to add new query parameters to an operation in future releases of a specification, as it changes the method definition. For example, if we were to add a new query parameter called optionalParam4, the method definition would then look like:

public String getItem(String requiredParam1, String requiredParam2, String optionalParam1, String optionalParam2, String optionalParam3, String optionalParam4) throws ApiException  { ... }

The user of the library is required to add null to all method invocations to allow their code to compile.

Users of the library should instead have the option of using the builder pattern to provide an optional options object, rather than a list of parameters.

For example:

public String getItem(String requiredParam1, String requiredParam2, Api.GetItemOptionals optionals) throws ApiException { ... }

[...]

String response = apiClient.getItem("foo", "bar", new Api.GetItemOptionals().optionalParam1(foo).optionalParam4(bar));

Swagger-codegen version

This issue is present in the latest versions of swagger-codegen 2.x (2.4.13) and 3.x (3.0.19).

Swagger declaration file content or url

swagger: '2.0'
info:
  version: 1.0.0
  title: Test
host: example.com
basePath: /
paths:
  /:
    get:
      operationId: getItem
      parameters:
        - name: requiredParam1
          in: query
          required: true
          type: string
        - name: requiredParam2
          in: query
          required: true
          type: string
        - name: optionalParam1
          in: query
          required: false
          type: string
        - name: optionalParam2
          in: query
          required: false
          type: string
        - name: optionalParam3
          in: query
          required: false
          type: string
      responses:
        '200':
          description: successful operation
          schema:
            type: string

Command line used for generation

Default options for Java:

java -jar swagger-codegen-cli.jar generate -i sample.yaml -l java

Related issues/PRs

There are some issues (e.g. #4386) related to adding builder pattern support for models, and one issue (#7115) about the backwards compatibility issue described above -- though with no proposed fix.

Start with the Java generator entry point and run the documented swagger-codegen command against the sample YAML to inspect the generated API method. Trace how required and optional query parameters become method signatures, then verify that generated calls support an optional builder object without forcing null arguments when new optional parameters are added.