Java: Make it clearer which operation input parameters are required

Description

Today, in the DefaultAPI class, one method is generated for each operation, and each of these methods has one method parameter for each operation parameter. The only indication that a field is optional or required is a small text marked in brackets at the end of the @param for each method. Our API users don't usually seem to notice this and thus find it difficult to identify which parameters are required and which are optional

Note - I've identified the Java client here because it's the one most of our clients use. However, for example, the Python client doesn't mark which parameters are required and which are optional anywhere, so I suspect this is an improvement which could be made across many languages.

Swagger-codegen version

2.2.1

Swagger declaration file content or url

https://github.com/amadeus-travel-innovation-sandbox/sandbox-content/blob/master/swagger.yml

Command line used for generation

dateLibrary=joda

Steps to reproduce

Call http://api.sandbox.amadeus.com/swagger-codegen/java
See generated DefaultAPI class

Related issues

Potentially related to #2485

Suggest a Fix

There are a number of possible improvements I can suggest, but each of them has their pros and cons

• Start each @param documentation element by noting whether the element is required (might not be obvious enough, does not benefit from clear highlighting in Eclipse)
• Offer 2 DefaultAPI methods for each operation, if that operation has optional parameters. One method should take only the required parameters - the second should have all parameters (default APIs class could get long)
• Use the Optional class to denote optional elements in the input methods (method calls could get verbose)
• Require an input object for each method, where the object takes all required parameters in the construct and uses optional or setters for other parameters (big change, might be painful for short methods)

Start by reproducing the Java client generation described in the issue and inspect the generated DefaultAPI class using the linked swagger.yml. Review the related issue #2485 and compare the proposed approaches before selecting one. Done means the generated Java API clearly distinguishes required and optional operation parameters.