Some applications explicitly create the OpenApiFeature object to tailor its behavior before registering it with the server. If your pom.xml includes a dependency on the OpenAPI UI component, then any OpenApiFeature object your application builds prepares the default OpenAPI UI behavior, possibly modified as above by any UI settings you have in your configuration.

WebServer server = WebServer.builder()
        .config(config.get("server"))
        .addFeature(OpenApiFeature.create(config.get("openapi"))) 
        .routing(Main::routing)
        .build()
        .start();

• Add the OpenAPI feature to the server, configured using the openapi section of the configuration.

If your code invokes the OpenApiFeature.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 OpenApiUiConfig.Builder and invoke methods on it to set the UI behavior, then invoke the builder’s build method to create the OpenApiUi object.
2. Invoke the addService method on OpenApiFeature.Builder, passing the OpenApiUi object you prepared above.

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

Config openApiConfig = config.get("openapi"); 
WebServer server = WebServer.builder()
        .config(config.get("server"))
        .addFeature(OpenApiFeature.builder() 
                            .addService(OpenApiUi.builder() 
                                                .webContext("my-ui") 
                                                .config(openApiConfig.get("ui")) 
                                                .build())
                            .config(openApiConfig)
                            .build())
        .routing(Main::routing)
        .build()
        .start();

• Extract the openapi config.
• Begin setting up the OpenApiFeature builder.
• Create the UI builder.
• Set UI behavior programmatically.
• Set additional UI behavior based on UI configuration.

The order in which your code invokes the methods on OpenApiUi.Builder and OpenApiFeature.Builder determines the outcome. For instance, the example above adds the UI service to the OpenApiFeature.Builder before applying configuration to the OpenApiFeature.Builder. If the configuration contains a setting for the UI web-context value, then the UI uses the configured value and not the programmatic value because your code applies 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.

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

You can use configuration to affect the UI path in these 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.

  Configure OpenAPI behavior

  server:
    port: 8080                  
    host: 0.0.0.0
    features:
      openapi:                  
        web-context: /myopenapi 

  content_copy Copied
  • The port and host settings are for the server as a whole, not specifically for OpenAPI.
  • The openapi subsection within features contains OpenAPI settings.
  • Changes the endpoint for returning the OpenAPI document from the default /openapi to /myopenapi.

  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 /myopenapi/ui and Helidon uses standard content negotiation at /myopenapi 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

  server:
    port: 8080
    host: 0.0.0.0
    features:
      openapi:
        services:
          ui:                     
            web-context: /my-ui   

  content_copy Copied
  • Introduces OpenAPI UI settings
  • Specifies an alternate path for the UI

  Note

  The server.features.openapi.services.ui.web-context setting assigns the entire web-context for the UI, not the suffix appended to the OpenApiFeature 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 server.features.openapi.services.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.