[Java] Generated Java APIs often have too many method parameters

[Kiran-Sivakumar]

Description

APIs often have a lot of optional parameters. This does not cause a problem for SDKs generated in languages that inherently support methods with optional parameters. However, in Java, arguments must be explicitly specified for all parameters, even the ones marked as "optional" in the specification. This can make OpenAPI-generated Java SDKs incredibly cumbersome to use.

openapi-generator version

3.3.0

OpenAPI declaration file content or url

Command line used for generation

Steps to reproduce

Related issues/PRs

Suggest a fix/enhancement

Here is a method generated by the current openapi-generator version, along with a call to the method:

/**
 * Create a new media collection
 *
 * @param requiredParam1 (required)
 * @param optionalParam1 (optional)
 * @param optionalParam2 (optional)
 * @param optionalParam3 (optional)
 * @param optionalParam4 (optional)
 * @param optionalParam5 (optional)
 * @param optionalParam6 (optional)
 * @return Collection
*/
public Collection createCollection(
    String requiredParam1,
    String optionalParam1,
    String optionalParam2,
    String optionalParam3,
    String optionalParam4,
    String optionalParam5,
    String optionalParam6
) {
    // ...
}

// ...

Collection collection = 
    api.createCollection("VALUE_A", "VALUE_B", null, "VALUE_C", null, null, null);

Users of the SDK are required to pass in some null value for optional parameters they do not use.

A much better solution would be to generate Java APIs that employ the builder pattern or something similar. This would allow for the following, much nicer code.

Collection collection = api.createCollection("VALUE_A")
        .optionalParameter1("VALUE_B")
        .optionalParameter3("VALUE_C")
        .execute();

The above code is similar to the code employed by the Google API Client Library (https://developers.google.com/api-client-library/java/). APIs for endpoints that only have required parameters (no optionals) need not be changed. They can be generated in the current way, although changing them to use the above style as well would consolidate everything nicely.

[Kiran-Sivakumar]

Another reason why the current method signatures should be changed is that whenever a new optional parameter is added to an API specification, SDK users who do not use that parameter will have to specify an additional "null" argument if they want their code to compile with the newly generated SDK. This is pretty unreasonable from a maintenance standpoint.

The proposed solution does not have this issue, requiring no changes when upgrading.