You can use the OpenAPI generator to create a new project or to generate files into an existing project. Some developers do both, using the generator to create the project at first and then to update the project as they evolve the OpenAPI document or change the generation options they select. Others create the project in some other way—​for example, using the Helidon CLI. The OpenAPI generator CLI and plug-in both support each type of usage.

If the OpenAPI generator finds a pre-existing API or model file, it overwrites it with the latest content. It does not overwrite a pom.xml file or test files. This is important because certain generation settings can influence the generated dependencies in the pom.xml file. For example, the serializationLibrary setting creates dependencies on either JSON-B or Jackson artifacts. As a result, changing the generation options can change the dependencies your project should have. If you rerun the generator, the old pom.xml remains and does not reflect the revised depencencies.

As a practical matter, many developers use the OpenAPI generators in one of the following ways:

• Use the generator CLI once to create a new project.

  By default, the generator CLI creates files in the normal Maven project structure: src/main/java, etc. Then you add your own files to that same project structure. Because the generated files are in the standard places, the project build includes them by default.

  Note

  You can run the generator CLI again to update the generated files. Because this happens outside the project’s build lifecycle, you need to remember to rerun the CLI yourself when you change the OpenAPI document.

  You also need to identify and manually remove any previously-generated files that become obsolete. Similarly, you must understand how changes in the OpenAPI document or the generation options affect the project dependencies and update the project pom.xml accordingly.

• Use the generator plug-in to (re)generate files during each build.

  Specify in the plug-in configuration that the generated files should reside in target/generated-sources directory (the conventional location for generated sources) or a subdirectory below there. Each project build runs the OpenAPI generator which reads the then-current OpenAPI document file. With the generated files under target, you can use mvn clean to remove any obsolete generated files left over from previous builds.

  Note

  In particular, with mvn clean each build regenerates the candidate pom.xml under target/generated-sources. You can inspect the generated pom.xml file for changes in dependencies and make any necessary changes in the actual project pom.xml file.

As you generate a Helidon SE server, you can choose whether you want Java interfaces or classes to represent the RESTful API endpoints.

By default, the Helidon OpenAPI server generator creates classes. You write your own concrete subclasses which extend those generated classes, supplying the business logic for each REST endpoint. Do not modify the generated classes.

If you set useAbstractClasses=false then the generator creates Java interfaces instead of classes. You then write classes which implement those generated interfaces.

Either way, you can safely regenerate the code later so long as you have not edited the generated code. The generator replaces the generated classes or interfaces but does not touch other classes you wrote.

The Helidon client generator always creates concrete classes. Typically, you do not need to customize the behavior in the generated client API classes. If you choose to do so, write your own subclass of the generated client API class; do not modify the generated files.

Each operation in an OpenAPI document can have a tags attribute. The generators group operations with the same tags value into the same API.

When you generate a Helidon SE server, the generator creates a separate interface or class for each API your service exposes. You implement each interface or extend each class to add your business logic for that API.

When you generate a Helidon SE client, the generated code contains a separate API class for each distinct API your code might invoke.

The following example uses the Helidon server generator to create a project or regenerate files into an existing project.

java -jar ${path-to-generator}/openapi-generator-cli.jar \
  generate \
  -i src/main/resources/petstore.yaml \
  -g java-helidon-server \
  --library se \
  -p groupId=io.helidon.examples \
  -p artifactId=helidon-openapigen-se-server \
  -p artifactVersion=1.0.0-SNAPSHOT \
  -p apiPackage=io.helidon.examples.openapigen.se.server.api \
  -p modelPackage=io.helidon.examples.openapigen.se.server.model \
  -p invokerPackage=io.helidon.examples.openapigen.se.server

The next example runs the Helidon client generator using the same input file.

java -jar ${path-to-generator}/openapi-generator-cli.jar \
  generate \
  -i src/main/resources/petstore.yaml \
  -g java-helidon-client \
  --library se \
  -p groupId=io.helidon.examples \
  -p artifactId=helidon-openapigen-se-client \
  -p artifactVersion=1.0.0-SNAPSHOT \
  -p apiPackage=io.helidon.examples.openapigen.se.client.api \
  -p modelPackage=io.helidon.examples.openapigen.se.client.model \
  -p invokerPackage=io.helidon.examples.openapigen.se.client

The key differences between the commands are:

• the generator selected by the -g option (client vs. server),

• the artifact ID and package names (client vs. server).

You could use these two commands together to generate a server submodule and a client submodule in a pre-existing multi-module Maven project. Remember that the resulting client project can access any server which implements the API described in the petstore.yaml OpenAPI document, whether it was generated using the OpenAPI generator tool or not.

In both examples, the generator creates the entire project if it does not exist and recreates the generated API and model files if the project already exists. The generator does not overwrite an existing pom.xml file, previously-generated test files, or files you create yourself.

You can run the OpenAPI generator plug-in as part of your project build to generate or regenerate files.

First, declare the plug-in as explained in the earlier section on Maven coordinates.

Then, in the <build> section of your pom.xml file, add an execution of the plug-in with the configuration you want. By default, the plug-in runs during the generate-sources phase of the Maven build.

The plug-in execution in the following example is equivalent to the CLI example above for generating server files:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/petstore.yaml</inputSpec>
                <generatorName>java-helidon-client</generatorName>
                <library>se</library>
                <output>${project.build.directory}/generated-sources/client</output> 
                <addCompileSourceRoot>true</addCompileSourceRoot>
                <configOptions>
                    <groupId>io.helidon.examples</groupId>
                    <artifactId>helidon-openapigen-se-client</artifactId>
                    <artifactVersion>1.0.0-SNAPSHOT</artifactVersion>
                    <apiPackage>io.helidon.examples.openapigen.se.client.api</apiPackage>
                    <modelPackage>io.helidon.examples.openapigen.se.client.model</modelPackage>
                    <invokerPackage>io.helidon.examples.openapigen.se.client</invokerPackage>
                </configOptions>
                <additionalProperties>
                    <additionalProperty>returnResponse=true</additionalProperty>
                </additionalProperties>
            </configuration>
        </execution>
    </executions>
</plugin>

• Specifies that the generated files should reside in the target/generated-sources/client directory.

The OpenAPI tools project hosts and maintains the online OpenAPI generator at http://api.openapi-generator.tech. You can use the site’s API browser to explore the available generators and the settings each supports, expressed as JSON.

To generate your project, you supply the options and additional properties as JSON. The online generator provides you with a file ID, and you refer to the file ID in a subsequent HTTP request to retrieve your project.

This document does not explore further the use of the online generator.

The Helidon SE client generator gives you as much flexibility as you need in connecting to the remote service.

Internally, the ApiClient uses a Helidon WebClient object to contact the remote system. The ApiClient.Builder automatically prepares a Helidon WebClient.Builder object using information from the OpenAPI document.

The next sections describe, from simplest to most complicated, the ways your code can create an ApiClient instance, each involving increased involvement with the WebClient.Builder object.

Accepting the Automatic WebClient.Builder

ApiClient apiClient = ApiClient.builder().build();

Influencing the Automatic WebClient.Builder

ApiClient apiClient = apiClient.builder()
                            .objectMapper(yourCustomMapper)
                            .build();

Adjusting the Automatic WebClient.Builder

ApiClient.Builder apiClientBuilder = ApiClient.builder();

apiClientBuilder.webClientBuilder() 
                .connectTimeout(4, TimeUnit.SECONDS); 

ApiClient apiClient = apiClientBuilder.build(); 

Providing a Custom WebClient.Builder

WebClient.Builder customWebClientBuilder = WebClient.builder()
                .connectTimeout(3, TimeUnit.SECONDS)
                .baseUri("https://myservice.mycompany.com");

ApiClient apiClient = ApiClient.builder()
                        .webClientBuilder(customWebClientBuilder)
                        .build();

The ApiClient represents the connection to the remote server but not the individual RESTful operations. Each generated xxxApi interface exposes a method for each operation declared in the OpenAPI document associated with that API via its tags value. By example, the PetApi interface exposes a method for each operation in the OpenAPI document that pertains to pets.

To invoke an operation defined on the PetApi interface, your code instantiates a PetApi using an ApiClient object:

ApiClient apiClient = ApiClient.builder().build();
PetApi petApi = PetApiImpl.create(apiClient);

With the petApi object, your code can invoke any of the methods on the PetApi interface to contact the remote service.

The Helidon WebClient follows a reactive programming model, and the Helidon SE client generator creates an ApiResponse interface, also reactive. Each generated PetApi method returns an ApiResponse<returnType> where the returnType is the return type declared in the OpenAPI document for the corresponding operation.

The ApiResponse interface exposes two methods your code can use to work with the response from the remote service invocation:

• Single<T> result()

  Provides reactive access to the value returned by the remote service in the response. This method lets your code fetch the return value directly.

• Single<WebClientResponse> webClientResponse()

  Provides reactive access to the Helidon WebClientResponse object. Your code can find out the HTTP return status, read headers in the response, and process the content (if any) in the response however it needs to.

In the reactive Helidon WebClient model, the first part of the response message can arrive (the status and headers are available) before the entity in the body of the response is readable. So there are two reactive events associated with an incoming HTTP response:

1. when the response excluding the entity content has arrived, and
2. when your code can begin consuming the entity content.

You can adopt different styles of retrieving the results, depending on the specific needs of the code you are writing.

Synchronous access to the result

// Assumes the petApi field is initialized as above.
List<Pet> availablePets = petApi.findPetsByStatus(List.of(Pet.StatusEnum.AVAILABLE.value())) 
                .result() 
                .await(4, TimeUnit.SECONDS); 

Synchronous access with status checking

ApiResponse<List<Pet>> apiResponse = petApi.findPetsByStatus(List.of(Pet.StatusEnum.AVAILABLE.value())); 

WebClientResponse webClientResponse = apiResponse.webClientResponse()
            .await(4, TimeUnit.SECONDS); 

if (webClientResponse.status().code() != 200) { 
    // Handle a non-successful status.
}

List<Pet>> availablePets = apiResponse.result()
            .await(4, TimeUnit.SECONDS); 

Fully-reactive access

// Assumes the petApi field is initialized as above.
ApiResponse<List<Pet>> availablePetsResponse =
    petApi.findPetsByStatus(List.of(Pet.StatusEnum.AVAILABLE.value())); 

availablePetsResponse.webClientResponse()
    .thenAccept(resp -> { 
        if (resp.status().code() == 200) {
            try {
                availablePetsResponse.result() 
                    .thenAccept(availablePets -> {
                        // Process the List<Pet> of available pets. 

                    })
                    .exceptionally(throwable -> {
                        // Handle whatever problem occurred in retrieving the results. 
                        return null;
                    });
            } catch (ExecutionException | InterruptedException e) {
                // Handle errors while waiting for the response content to arrive. 
            }
        } else {
            // Handle non-200 HTTP status. 
        })
    .exceptionally(throwable -> {
        // Handle whatever problem occurred in receiving the response. 
        return null;
    });