se.openapi.openapi.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2019, 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 in Helidon
:description: Helidon SE OpenAPI Support
:keywords: helidon, se, openapi
:feature-name: OpenAPI
:rootdir: {docdir}/../..
:incdir: {rootdir}/includes/openapi
include::{rootdir}/includes/se.adoc[]
:javadoc-path: {openapi-javadoc-base-url}/io.helidon.openapi
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
include::{incdir}/openapi.adoc[tag=overview]
include::{rootdir}/includes/dependencies.adoc[]
// tag::depc[]
[source,xml]
----
io.helidon.openapi
helidon-openapi
----
// end::depc[]
== Usage
=== Automatic Registration (default)
Simply by adding the dependency described above you add support for OpenAPI to your Helidon SE application. Because Helidon
automatically discovers the OpenAPI feature, you do not have to make any changes to your application code.
=== Explicit Registration
To control the behavior of the OpenAPI feature programmatically, you can add and configure the OpenAPI feature explicitly as
explained below.
==== Create and Register `OpenApiFeature` in your application
Helidon SE provides the link:{openapi-javadoc-base-url}/io/helidon/openapi/OpenApiFeature.html[`OpenApiFeature`] class
which your application uses to assemble the in-memory model and expose the `/openapi` endpoint to clients. You can
create an instance either using a static `create` method or by instantiating its
link:{openapi-javadoc-base-url}/io/helidon/openapi/OpenApiFeatureConfig.Builder.html[`Builder`].
The xref:#register_openapifeature[example below] illustrates one way to do this.
include::{incdir}/openapi.adoc[tag=furnish-openapi-info]
include::{incdir}/openapi.adoc[tag=usage-access-endpoint]
== API
Helidon {flavor-uc} provides an API for creating and setting up the REST endpoint which serves OpenAPI documents to clients
at the `/openapi` path. Use either static methods on link:{openapi-javadoc-base-url}/io/helidon/openapi/OpenApiFeature.html[`OpenApiFeature`]
or use its link:{openapi-javadoc-base-url}/io/helidon/openapi/OpenApiFeatureConfig.Builder.html[`Builder`].
Then add that instance or builder to your application's routing. The <<#register_openapifeature,example>> below shows how to do this.
[[config]]
== Configuration
Helidon SE OpenAPI configuration supports the following settings:
include::{rootdir}/config/io_helidon_openapi_OpenApiFeature.adoc[leveloffset=+1,tag=config]
== Examples
Helidon SE provides a link:{helidon-github-examples-url}/openapi[complete OpenAPI example]
based on the SE QuickStart sample app.
Most Helidon {flavor-uc} applications need only add the dependency as explained above; Helidon discovers and registers OpenAPI
automatically. The example below shows how to create and register `OpenApiFeature` explicitly instead.
[[register_openapifeature]]
=== Register `OpenApiFeature` explicitly
.Java Code to Create and Register `OpenApiFeature`
[source,java]
----
include::{sourcedir}/se/openapi/OpenApiSnippets.java[tag=snippet_1, indent=0]
----
<1> Adds the `OpenApiFeature` service to your server using the `openapi` section from configuration.
If you need programmatic control over the `OpenApiFeature` instance, invoke `OpenApiFeature.builder()` to get an
`OpenApiFeature.Builder` object and work with it, then invoke the builder's `build` method and pass the resulting
`OpenApiFeature` instance to the `WebServer.Builder` `addFeature` method.