Add support for asynchronous API for JavaJaxRsSpec

Created by: tbredzin

resolves #4832 (closed) This PR is an attempt at addressing https://github.com/OpenAPITools/openapi-generator/issues/4832

Motivation

Since version 2.1, JAX-RS server side component has support for returning a CompletionStage to mark the request as eligible for asynchronous processing. The advantage this approach has over the AsyncResponse based API is that it is richer and allows you to create asynchronous pipelines.

It is also extended by 3rd party libraries such as Reactor, RxJava or Mutiny. All of those allow to convert from/to CompletionStage, examples:

• Reactor:

CompletionStage<String> single = Mono.just("something").toFuture();
CompletionStage<List<String>> many = Flux.just("something", "somethingelse")
                .collectList()
                .toFuture()

• RxJava3

CompletionStage<String> single = Maybe.just("something").toCompletionStage();
CompletionStage<List<String>> many = Flowable.fromArray("something", "somethingelse")
                .toList()
                .toCompletionStage();

• Mutiny

CompletionStage<String> single = Uni.createFrom().item("something").subscribeAsCompletionStage();
CompletionStage<List<String> many = Multi.createFrom().items("something", "somethingelse")
                .collect()
                .asList()
                .subscribeAsCompletionStage();

Code changes

This PR adds the option supportAsync to the Java JAX-RS spec generator and updates the mustache templates.

When set to true, the generated API interfaces and classes will return CompletionStage to support running asynchronous operation in JAX-RS (supported since JAX-RS 2.1).

This option also enables java8 mode as CompletionStage requires a JDK > 1.8

Tests

Unit Tested for:

• Generation with interfaceOnly=true with the petstore.yaml file
• Generation with interfaceOnly=true for complex types with the ping.yaml file
• Generation with interfaceOnly=true for primitive types with the issue_4832.yaml file
• Generation with interfaceOnly=true and returnResponse=true with the ping.yaml file
• Generation with interfaceOnly=false classes with ping.yaml

Sample of generated API interfaces (interfaceOnly=true):

//PingApi.java w/  returnResponse=true
CompletionStage<Response> pingGet();

// PetApi.java w/ returnResponse=false
CompletionStage<Pet> getPetById(@PathParam("petId") @ApiParam("ID of pet to return") Long petId);
CompletionStage<List<Pet>> findPetsByStatus(@QueryParam("status") @NotNull  @ApiParam("Status values that need to be considered for filter")  List<String> status);

//FakeApi.java
CompletionStage<Boolean> getBool(); //primitive type converted to class

// StoreApi.java
CompletionStage<Map<String, Integer>> getInventory();
CompletionStage<Order> placeOrder(@Valid @NotNull Order order);
CompletionStage<Void> deleteOrder(@PathParam("orderId") @ApiParam("ID of the order that needs to be deleted") String orderId);

Sample of generated API class (interfaceOnly=false):

public CompletionStage<Response> pingGet() {
    return CompletableFuture.supplyAsync(() -> Response.ok().entity("magic!").build());
}

Note that the current implementation from master, always returns Response. So no specific types are returned with supportAsync=true too: CompletionStage<Response>.

Project generated from it was compile successfully after running:

$ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g jaxrs-spec -p interfaceOnly=true,supportAsync=true -o ~/tmp

$ cd ~/tmp 
$ mvn clean package

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh
  ./bin/utils/export_docs_generators.sh

  Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
• File the PR against the correct branch: master (5.3.0), 6.0.x
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request. @nmuesch