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. By default, the generators group operations with the same tags value into the same API or service. Alternatively, if you specify the option x-helidon-groupBy as first-path-segment, the generators use the first segment of the path to group operations together.

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.

The generator creates Helidon routing logic based on the longest common path prefix shared among the operations that are grouped into each 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 generator creates an implementation class as well as the abstract class for each API. The implementation class contains a handle method for each API operation with a very simple method body that returns a not-yet-implemented HTTP status in the response. The following example shows the generated method for the addPet OpenAPI operation.

public class PetServiceImpl extends PetService {
    @Override
    protected void handleAddPet(ServerRequest request, ServerResponse response,
                                Pet pet) {
        response.status(Status.NOT_IMPLEMENTED_501).send();
    }
}

Customize the class to manage the pets and revise the method to save the new pet and send the correct response, as shown next.

public class PetServiceImpl extends PetService {

    private final Map<Long, Pet> pets = new HashMap<>(); 

    @Override
    protected void handleAddPet(ServerRequest request, ServerResponse response,
                                Pet pet) {
        if (pets.containsKey(pet.getId())) { 
            AddPetOp.Response405.builder().send(response);
        }
        pets.put(pet.getId(), pet); 
        AddPetOp.Response200.builder().send(response); 
    }
}

• Business logic: create a very simple data store - a real app would use a database.
• Business logic: make sure the pet being added does not already exist. Send the invalid request status code if it does.
• Business logic: add the pet to the data store.
• Prepare and send the 200 response.

If a response has any required response parameters you would pass them as parameters to the builder method. Add optional response parameters using other generated builder methods. The following example illustrates this for the findPetsByTags operation and its response output parameter.

public class PetServiceImpl extends PetService {

    private final Map<Long, Pet> pets = new HashMap<>(); 

    @Override
    protected void handleFindPetsByTags(ServerRequest request, ServerResponse response,
                                        List<String> tags) { 

        List<Pet> result = pets.values().stream()
                .filter(pet -> pet.getTags()
                        .stream()
                        .anyMatch(petTag -> tags.contains(petTag.getName())))
                .toList(); 

        FindPetsByTagsOp.Response200.builder() 
                .response(result) 
                .send(response); 

    }
}

• Uses the same data store as in the earlier example.
• The tags parameter conveys the tag values to be matched in selecting pets to report. Other generated code extracts the runtime argument’s value from the request and then automatically passes it to the method.
• Collects all pets with any tag that matches any of the selection tags passed in.
• Uses the generated Response200 to prepare the response.
• Assigns the optional response output parameter—​the list of matching Pet objects.
• Send the response using the prepared response information.

Write each of the handleXxx methods appropriately so they implement the business logic you need and send the response.

The generator creates a ResponseNNN Java record for each operation response status code NNN that is declared in the OpenAPI document. You can return other status values with other output parameters even if they are not declared in the OpenAPI document, but your code must prepare the ServerResponse entirely by itself; the generator cannot generate helper records for responses that are absent from the document.

Generated code takes care of the following work:

• Route each request to the method which should respond.

• Extract each incoming parameter from the request and convert it to the correct type, applying any validation declared in the OpenAPI document.

• Pass the extracted parameters to the developer-written handleXxx method.

• Assemble required and optional response parameters and send the response.

You can override any of the generated behavior by adding code to the generated API implementation class you are already editing to customize the handleXxx methods and by writing new classes which extend some of the generated classes.

Override routing

Override how to extract one or more parameters from a request

Override how an operation is prepared from a request

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 WebClientConfig.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 WebClientConfig.Builder object.

Accepting the Automatic WebClientConfig.Builder

public class ExampleClient {

    private ApiClient apiClient; 

    void init() {
        ApiClient apiClient = ApiClient.builder().build(); 
    }
}

Influencing the Automatic WebClientConfig.Builder

public class ExampleClient {

    private ApiClient apiClient; 

    void init() {
        ObjectMapper myObjectMapper = new ObjectMapper(); 
        apiClient = ApiClient.builder()
                .objectMapper(myObjectMapper) 
                .build();
    }
}

Adjusting the Automatic WebClientConfig.Builder

public class ExampleClient {

    private ApiClient apiClient; 

    void init() {
        ApiClient.Builder apiClientAdjustedBuilder = ApiClient.builder(); 

        apiClientAdjustedBuilder
                .webClientBuilder() 
                .connectTimeout(Duration.ofSeconds(4)); 

        apiClient = apiClientAdjustedBuilder.build(); 
    }
}

Providing a Custom WebClientConfig.Builder

public class ExampleClient {

    private ApiClient apiClient; 

    void init() {
        WebClientConfig.Builder customWebClientBuilder = WebClient.builder() 
                .connectTimeout(Duration.ofSeconds(3)) 
                .baseUri("https://myservice.mycompany.com"); 

        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:

public class ExampleClient {

    private ApiClient apiClient; 

    private PetApi petApi; 

    void preparePetApi() {
        petApi = PetApiImpl.create(apiClient); 
    }
}

• Stores a reusable AppClient.
• Stores a reusable PetApi for invoking pet-related operations.
• Initializes and saves the PetApi instance using the previously-prepared apiClient.

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

The Helidon SE client generator creates an ApiResponse interface. Each generated PetApi method returns an ApiResponse<returnType> where the returnType is the return type (if any) 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:

• T result()

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

• HTTPClientResponse webClientResponse()

  Provides access to the Helidon HTTPClientResponse 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 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 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.

Access only the result

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

    List<Pet> availablePets = apiResponse.result(); 
}

Access with status checking

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

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

    List<Pet> avlPets = apiResponse.result(); 
}