With the Helidon OpenAPI UI dependency in your pom.xml file, any OpenAPISupport object your application builds prepares the default OpenAPI UI behavior, possibly modified by any UI settings you have in your configuration.

Config config = Config.create(); 
Config openApiConfig = config.get(OpenAPISupport.Builder.CONFIG_KEY)); 

OpenAPISupport openApiSupport =
    OpenAPISupport.builder()
        .config(openApiConfig) 
        .build();

• Load the configuration.
• Extract the OpenAPISupport configuration.
• Build the OpenAPISupport instance using the configuration.

If your code invokes the OpenAPISupport.Builder config method, Helidon automatically applies the ui section of the openapi configuration to the UI.

You can control some of the behavior of the UI programmatically in two steps:

1. Create an OpenApiUi.Builder and invoke methods on it to set the UI behavior.
2. Invoke the ui method on OpenAPISupport.Builder, passing the OpenApiUi.Builder you prepared above.

The following example illustrates these steps, combining configuration with explicit programmatic settings.

Config config = Config.create(); 
Config openApiConfig = config.get(OpenAPISupport.Builder.CONFIG_KEY)); 

OpenApiUi.Builder uiBuilder =
    OpenApiUi.builder() 
        .webContext("/my-openapi-ui"); 

OpenAPISupport openApiSupport =
    OpenAPISupport.builder() 
        .ui(uiBuilder)
        .config(openApiConfig) 
        .build();

• Load the configuration.
• Extract the OpenAPISupport configuration.
• Create the OpenApiUi.Builder instance.
• Explicitly set the web context where the UI should respond.
• Create the OpenAPISupport instance using the OpenApiUi.Builder just created. You can refine the behavior of the OpenAPISupport object by invoking additional methods on its builder before invoking its build method.
• Apply the openapi configuration to the OpenAPISupport builder. This also automatically applies any openapi.ui configuration to the UI.

The order in which your code invokes the methods on OpenApiUi.Builder and OpenAPISupport.Builder determines the outcome. For instance, the example above sets the UI on the OpenAPISupport.Builder before applying configuration. If the configuration contains a setting for the UI’s web-context value then the UI uses the configured value, not the programmatic value, because your code applied the configuration later. Your code should typically apply configuration after setting any values programmatically. Doing so allows users or deployers of your service to set the behavior using configuration according to their particular needs which your code might not be able to anticipate.

Whether or not your code tailors the UI or OpenAPISupport behavior, it must register the resulting OpenAPISupport instance so that the OpenAPI and UI endpoints can respond correctly.

Routing.builder()
        .register(openApiSupport)
        // Add registrations of your service(s) and other Helidon services you need.
        .build();

The UI is implemented as part of the OpenAPISupport service which registers the UI automatically. Your code does not register the UI explicitly.

The default UI web-context value is the web context for your OpenAPISupport service with the added suffix /ui. If you use the default web context for both OpenAPISupport and the UI, the UI responds at /openapi/ui.

You can use configuration to affect the UI path in two ways:

• Configure the OpenAPI endpoint path (the /openapi part).

  Recall that you can configure the Helidon OpenAPI component to change where it serves the OpenAPI document.

  Configuring the OpenAPI web context

  openapi:
    web-context: /my-openapi

  content_copy Copied

  In this case, the path for the UI component is your customized OpenAPI path with /ui as a suffix. With the example above, the UI responds at /my-openapi/ui and Helidon uses standard content negotiation at /my-openapi to return either the OpenAPI document or the UI.

• Separately, configure the entire web context path for the UI independently from the web context for OpenAPI.

  Configuring the OpenAPI UI web context

  openapi:
    ui:
      web-context: /my-ui

  content_copy Copied

  Note

  The openapi.ui.web-context setting assigns the entire web-context for the UI, not the suffix appended to the OpenAPISupport endpoint.

  With this configuration, the UI responds at /my-ui regardless of the path for OpenAPI itself.

The SmallRye OpenAPI UI component accepts several options, but they are of minimal use to application developers and they must be passed to the SmallRye UI code programmatically. Helidon allows you to specify these values using configuration in the openapi.ui.options section. Helidon then passes the corresponding options to SmallRye for you. To configure any of these settings, use the enum values—​they are all lower case—​declared in the SmallRye Option.java class as the keys in your Helidon configuration.