mp.openapi.openapi.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
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 MP OpenAPI Support
:keywords: helidon, mp, microprofile, openapi
:feature-name: MicroProfile OpenAPI
:microprofile-bundle: true
:rootdir: {docdir}/../..
:incdir: {rootdir}/includes/openapi
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
include::{incdir}/openapi.adoc[tag=overview]
include::{rootdir}/includes/dependencies.adoc[]
[source,xml,subs="attributes+"]
----
include::{incdir}/openapi.adoc[tag=mp-depc]
----
If you do not use the `helidon-microprofile-bundle` also add the following dependency which defines the MicroProfile OpenAPI annotations so you can use them in your code:
[source,xml]
----
org.eclipse.microprofile.openapi
microprofile-openapi-api
----
== Usage
=== OpenAPI support in Helidon MP
You can very simply add support for OpenAPI to your Helidon MP application. This
document shows what changes you need to make to your application and how to access
the OpenAPI document for your application at runtime.
=== Changing your application
To use OpenAPI from your Helidon MP app, in addition to adding dependencies as described above:
1. Furnish OpenAPI information about your application's endpoints.
2. Update your application's configuration (optional).
include::{incdir}/openapi.adoc[tag=furnish-openapi-info]
=== Update your application configuration
Beyond the two config properties that denote the model reader and filter, Helidon
MP OpenAPI supports a number of other mandated settings. These are described in the
link:{microprofile-open-api-spec-url}#configuration[configuration section] of the MicroProfile
OpenAPI spec.
include::{incdir}/openapi.adoc[tag=usage-access-endpoint]
== API
include::{incdir}/openapi.adoc[tag=api]
== Configuration
Helidon OpenAPI configuration supports the following settings:
include::{rootdir}/config/io_helidon_openapi_OpenApiFeature.adoc[leveloffset=+1,tag=config]
Further, Helidon OpenAPI supports the MicroProfile OpenAPI settings described in link:{microprofile-open-api-spec-url}#_configuration[the MicroProfile OpenAPI specification].
== Examples
Helidon MP includes a link:{helidon-github-examples-url}/microprofile/openapi[complete OpenAPI example]
based on the MP quick-start sample app. The rest of this section shows, step-by-step, how one might change the original QuickStart service to adopt OpenAPI.
=== Helidon MP OpenAPI Example
This example shows a simple greeting application, similar to the one from the
Helidon MP QuickStart, enhanced with OpenAPI support.
[source,java]
----
include::{sourcedir}/mp/openapi/OpenapiSnippets.java[tag=snippet_1, indent=0]
----
<1> With `@Operation` annotation we document the current method.
<2> With `@RequestBody` annotation we document the content produced. Internal annotations `@Content`, `@Schema` and
`@ExampleObjects` are used to give more details about the returned data.
If we want to hide a specific path an `OASFilter` is used.
The OASFilter interface allows application developers to receive callbacks for various key OpenAPI elements. The
interface has a default implementation for every method, which allows application developers to only override the
methods they care about. To use it, simply create an implementation of this interface and register it using the
`mp.openapi.filter configuration` key, where the value is the fully qualified name of the filter class.
The following example filter prevents information about a given path from appearing in the OpenAPI document.
[source,java]
----
include::{sourcedir}/mp/openapi/OpenapiSnippets.java[tag=snippet_2, indent=0]
----
You can implement a model reader to provide all or part of the in-memory `OpenAPI` model programmatically. Helidon
`OpenAPI` merges the model from the model reader with models from the other sources (a static file and annotations).
The example model reader below creates an `OpenAPI` object describing two paths. It turns out that the filter described
earlier will suppress one of the paths, but the model reader does not know or care.
[source,java]
----
include::{sourcedir}/mp/openapi/OpenapiSnippets.java[tag=snippet_3, indent=0]
----
Having written the filter and model reader classes, identify them by adding configuration to
`META-INF/microprofile-config.properties` as the following example shows.
[source,properties]
----
mp.openapi.filter=io.helidon.microprofile.examples.openapi.internal.SimpleAPIFilter
mp.openapi.model.reader=io.helidon.microprofile.examples.openapi.internal.SimpleAPIModelReader
----
Now just build and run:
[source,bash]
----
mvn package
java -jar target/helidon-examples-microprofile-openapi.jar
----
Try the endpoints:
[source,bash]
----
curl -X GET http://localhost:8080/greet
{"message":"Hello World!"}
curl -X GET http://localhost:8080/openapi
[lengthy OpenAPI document]
----
The output describes not only then endpoints from `GreetResource` but
also one contributed by the `SimpleAPIModelReader`.
Full example is available link:{helidon-github-examples-url}/microprofile/openapi[in our official repository]
== Additional Information
include::{incdir}/openapi.adoc[tag=additional-building-jandex]
== Reference
* link:https://github.com/eclipse/microprofile-open-api[MicroProfile OpenAPI GitHub Repository]
* link:{microprofile-open-api-spec-url}[MicroProfile OpenAPI Specification]