se.openapi.openapi-ui.adoc Maven / Gradle / Ivy

Go to download
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2022, 2024 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= OpenAPI UI
:description: Helidon SE OpenAPI UI Support
:keywords: helidon, se, openapi ui
:rootdir: {docdir}/../..
:ui-inc: {rootdir}/includes/openapi/openapi-ui.adoc

include::{rootdir}/includes/se.adoc[]

:javadoc-path: {openapi-ui-javadoc-base-url}/io/helidon/integrations/openapi/ui
:openapi-javadoc-path: {openapi-javadoc-base-url}/io/helidon/integrations/openapi

include::{ui-inc}[tag=preamble]

include::{ui-inc}[tags=intro;overview]

include::{ui-inc}[tag=dependencies]

Also, make sure your project has the following dependency.

include::{docdir}/openapi.adoc[tag=depc]

This dependency allows your application to create, configure, and register the `OpenApiFeature` service.

include::{ui-inc}[tag=usage]

== API
With the Helidon OpenAPI UI dependency in your `pom.xml` file, the OpenAPI support automatically includes the default UI behavior,
 possibly modified by any UI settings you have in your configuration. You do not have to do anything else to enable the UI.

=== Creating `OpenApiFeature` with Automatic UI Behavior
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.

[source,java]
.Create `OpenApiFeature` with automatic UI
----
include::{sourcedir}/se/openapi/OpenApiUiSnippets.java[tag=snippet_1, indent=0]
----
<1> 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.

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

. Create an link:{javadoc-path}/OpenApiUiConfig.Builder.html[`OpenApiUiConfig.Builder`] and invoke methods on it to set the UI behavior, then invoke the builder's `build` method to create the `OpenApiUi` object.
. Invoke the `addService` method on link:{openapi-javadoc-base-url}/io/helidon/openapi/OpenApiFeatureConfig.Builder.html[`OpenApiFeature.Builder`], passing the `OpenApiUi` object you prepared above.

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

[source,java]
.Create `OpenApiUi` and `OpenAPISupport` instances
----
include::{sourcedir}/se/openapi/OpenApiUiSnippets.java[tag=snippet_2, indent=0]
----
<1> Extract the `openapi` config.
<2> Begin setting up the `OpenApiFeature` builder.
<3> Create the UI builder.
<4> Set UI behavior programmatically.
<5> 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.

[NOTE]
====
The `webContext(String)` method on `OpenApiUi.Builder`  sets the web context where the UI should respond instead of the default `/openapi/ui`.
Helidon uses the provided string to set the _entire_ web context for the UI, not as a suffix appended to the web context for the `OpenAPISupport` service.
====

include::{ui-inc}[tag=config-intro]

include::{ui-inc}[tag=config-details]

include::{ui-inc}[tag=additional-info]