From 7b518720be61f90d5e0c409f31ea4533aaadf73f Mon Sep 17 00:00:00 2001 From: Tim Quinn Date: Wed, 18 Oct 2023 17:46:35 -0500 Subject: [PATCH] Updated OpenAPI and OpenAPI UI doc for 4.0 (#7823) --- docs/includes/openapi/openapi-ui.adoc | 18 ++-- docs/includes/openapi/openapi.adoc | 75 ++++++++-------- docs/mp/openapi/openapi.adoc | 10 ++- docs/se/openapi.adoc | 123 -------------------------- docs/se/openapi/openapi-ui.adoc | 103 ++++++++++----------- docs/se/openapi/openapi.adoc | 66 ++++++-------- 6 files changed, 127 insertions(+), 268 deletions(-) delete mode 100644 docs/se/openapi.adoc diff --git a/docs/includes/openapi/openapi-ui.adoc b/docs/includes/openapi/openapi-ui.adoc index 8b42d7f4298..83b8f3b3907 100644 --- a/docs/includes/openapi/openapi-ui.adoc +++ b/docs/includes/openapi/openapi-ui.adoc @@ -46,7 +46,11 @@ ifndef::rootdir[:rootdir: {docdir}/../..] SmallRye offers an link:{smallrye-openapi-ui-base-url}[OpenAPI user interface component] which displays a web page based on your application's OpenAPI document. Through that UI, users can invoke the operations declared in the document. -While not generally suitable for end-users, the OpenAPI UI can be useful for demonstrating and "test driving" your service's endpoints. + +[NOTE] +==== +The Helidon team discourages including the OpenAPI UI in production applications. The OpenAPI UI _can_ be useful for demonstrating and testing your service's endpoints prior to deployment. +==== The Helidon OpenAPI component allows you to integrate the SmallRye UI into your application, adding the UI web page to your application very simply. @@ -59,15 +63,15 @@ include::{rootdir}/includes/dependencies.adoc[] [source,xml,subs=+macros] ---- - io.helidon.openapi - helidon-openapi-ui + io.helidon.integrations.openapi-ui + helidon-integrations-openapi-ui ifdef::mp-flavor[ runtime] ---- And add a runtime dependency on the SmallRye UI. -[source,xml,subs=+macros] +[source,xml] ---- io.smallrye @@ -81,7 +85,7 @@ And add a runtime dependency on the SmallRye UI. // tag::usage-start[] == Usage ifdef::se-flavor[] -Make sure your application creates a Helidon `OpenAPISupport` instance and registers it for routing (described in detail in link:{openapi-page}[the Helidon OpenAPI documentation]). `OpenAPISupport` automatically prepares the OpenAPI UI with default settings if you also declare a dependency on the Helidon OpenAPI UI integration component as explained above. The <> section below illustrates adding OpenAPI to your application and customizing the UI behavior. +Make sure your application incorporates Helidon OpenAPI support as described in detail in link:{openapi-page}[the Helidon OpenAPI documentation]). Helidon automatically prepares the OpenAPI UI with default settings if you also declare a dependency on the Helidon OpenAPI UI integration component as explained above. The <> section below illustrates adding OpenAPI to your application and customizing the UI behavior. endif::se-flavor[] After you modify, build, and start your Helidon {flavor-uc} service, you can access the OpenAPI UI by default at `http://your-host:your-port/openapi/ui`. @@ -135,7 +139,7 @@ ifdef::mp-flavor[your `META-INF/microprofile-config.properties` file.] ifdef::se-flavor[your configuration file, such as `application.yaml`.] include::{rootdir}/config/io_helidon_integrations_openapi_ui_OpenApiUi.adoc[tag=config,leveloffset=+1] -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`. +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`. // end::config-intro[] @@ -185,7 +189,7 @@ endif::mp-flavor[] + [NOTE] ==== -The `openapi.ui.web-context` setting assigns the _entire_ web-context for the UI, not the suffix appended to the `OpenAPISupport` endpoint. +The `openapi.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. diff --git a/docs/includes/openapi/openapi.adoc b/docs/includes/openapi/openapi.adoc index ea3e628d03f..78666756dd0 100644 --- a/docs/includes/openapi/openapi.adoc +++ b/docs/includes/openapi/openapi.adoc @@ -25,25 +25,32 @@ The link:{microprofile-open-api-spec-url}[MicroProfile OpenAPI spec] explains ho ifdef::mp-flavor[Helidon {flavor-uc} implements the MicroProfile OpenAPI specification.] ifdef::se-flavor[OpenAPI support in Helidon {flavor-uc} draws its inspiration from MicroProfile OpenAPI but does not implement the spec because Helidon {flavor-uc} does not support annotations.] -ifdef::nima-flavor[OpenAPI support in Helidon {flavor-uc} draws its inspiration from MicroProfile OpenAPI but does not implement the spec because Helidon {flavor-uc} does not support annotations.] -The OpenAPI support in Helidon {flavor-uc} performs two main tasks: +The OpenAPI support in Helidon {flavor-uc} performs +two main tasks: * Build an in-memory model of the REST API your service implements. -* Expose the model in text format (typically YAML) via the `/openapi` endpoint. +* Expose the model in text format (YAML or JSON) via the `/openapi` endpoint. -To construct the model, Helidon gathers information about the service API from whichever of these sources are present in the application: +:static-source-info: a static OpenAPI document file packaged as part of your service +To construct the model, Helidon gathers information about the service API from +ifdef::se-flavor[] +{static-source-info}. +endif::se-flavor[] +ifdef::mp-flavor[] +whichever of these sources are present in the application: + +* {static-source-info}; ++ * a _model reader_ + The SPI defines an interface you can implement in your application for programmatically providing part or all of the model; -* a static OpenAPI document file packaged as part of your service; -ifdef::mp-flavor[] * OpenAPI annotations; -endif::[] * a _filter_ class + The SPI defines an interface you can implement in your application which can mask parts of the model. +endif::[] // end::overview[] @@ -64,8 +71,7 @@ The SPI defines an interface you can implement in your application which can mas // level 4 sections from here, and that led to errors with headers being out of sequence. // With the entire level 3 section here and conditional text for SE and MP, AsciiDoctor is happy. ifdef::se-flavor[] -OpenAPI support in Helidon SE largely follows the link:{microprofile-open-api-spec-url}[MicroProfile OpenAPI spec]. -But because Helidon SE does not process annotations, your application supplies data for the OpenAPI model in the other ways listed earlier. +Your application supplies data for the OpenAPI model using a static OpenAPI file. endif::[] ifdef::mp-flavor[] @@ -74,7 +80,7 @@ builds its in-memory model of your application's API. It constructs the OpenAPI document from this internal model. Your application can use one or more of these techniques. -===== Annotate the endpoints in your app +===== Annotations on the endpoints in your app You can add MicroProfile OpenAPI annotations to the endpoints in your source code. These annotations allow the Helidon MP OpenAPI runtime to discover the endpoints and information about them via CDI at app start-up. @@ -102,60 +108,53 @@ This excerpt shows only a few annotations for illustration. The link:{helidon-github-tree-url}/examples/microprofile/openapi-basic[Helidon MP OpenAPI example] illustrates more, and the link:{microprofile-open-api-spec-url}[MicroProfile OpenAPI spec] describes them all. -===== Provide a static OpenAPI file +===== A static OpenAPI file Add a static file at `META-INF/openapi.yml`, `META-INF/openapi.yaml`, or `META-INF/openapi.json`. Tools such as Swagger let you describe your app's API and they then generate an OpenAPI document file which you can include in your application so OpenAPI can use it. -===== Write and configure a model reader class +===== A model reader class your application provides Write a Java class that implements the OpenAPI link:{microprofile-open-api-javadoc-url}/OASModelReader.html[`org.eclipse.microprofile.openapi.OASModelReader`] interface. Your model reader code programmatically adds elements to the internal model that OpenAPI builds. +Then set the `mp.openapi.model.reader` configuration property to the fully-qualified name of your model reader class. + +===== A filter class your application provides +Write a Java class that implements the OpenAPI link:{microprofile-open-api-javadoc-url}/OASFilter.html[`org.eclipse.microprofile.openapi.OASFilter`] interface. +Helidon invokes your filter methods for each element of the in-memory model, allowing your code to modify an element or completely remove it from the model. + +Then set the `mp.openapi.filter` configuration property to the fully-qualified name of your filter class. + endif::[] +ifdef::se-flavor[] ===== Provide a static OpenAPI file Add a static file at `META-INF/openapi.yml`, `META-INF/openapi.yaml`, or `META-INF/openapi.json`. Tools such as Swagger let you describe your app's API and they then generate an OpenAPI document file which you can include in your application so OpenAPI can use it. -===== Write and configure a model reader class -Write a Java class that implements the OpenAPI -link:{microprofile-open-api-javadoc-url}/OASModelReader.html[`org.eclipse.microprofile.openapi.OASModelReader`] interface. Your -model reader code programmatically adds elements to the internal model that OpenAPI -builds. - -Change your application's MP configuration to set `mp.openapi.model.reader` as the -fully-qualified class name of your class. - -===== Write and configure a filter class -Write a Java class that implements the OpenAPI -link:{microprofile-open-api-javadoc-url}/OASFilter.html[`org.eclipse.microprofile.openapi.OASFilter`] interface. -As OpenAPI composes its internal model, it invokes your filter with each -model element _before_ adding the element to the model. Your filter can -accept the element as-is, modify it, or suppress it. - -Change your application's configuration to set `mp.openapi.filter` as the full-qualified -class name of your class. - +endif::se-flavor[] // end::furnish-openapi-info[] // tag::usage-access-endpoint[] === Accessing the REST Endpoint -Once you add the {flavor-uc} OpenAPI dependency to your -ifdef::mp-flavor[project,] -ifdef::se-flavor[project and add code to create the `OpenAPISupport` object to your routing,] -your application automatically responds to the built-in endpoint -- -`/openapi` -- and it returns the OpenAPI document describing the endpoints +Once you have added the {flavor-uc} OpenAPI dependency to your +ifdef::mp-flavor[project, then ] +ifdef::se-flavor[project, if you are using auto-discovery--or if you are not using auto-discovery and you have added code to register the `OpenApiFeature` object with your routing--then ] +your application responds to the built-in endpoint -- +`/openapi` -- and returns the OpenAPI document describing the endpoints in your application. -By default, per the MicroProfile OpenAPI spec, the default format of the OpenAPI document is YAML. +ifdef::mp-flavor[Per the MicroProfile OpenAPI spec, the] +ifdef::se-flavor[The] +default format of the OpenAPI document is YAML. There is not yet an adopted IANA YAML media type, but a proposed one specifically for OpenAPI documents that has some support is `application/vnd.oai.openapi`. -That is what Helidon returns, by default. +That is what Helidon returns by default. In addition, a client can specify the HTTP header `Accept` as either `application/vnd.oai.openapi+json` or `application/json` to request JSON. Alternatively, the client can pass the query parameter `format` as either `JSON` diff --git a/docs/mp/openapi/openapi.adoc b/docs/mp/openapi/openapi.adoc index c63618fcd94..0b28be2e38e 100644 --- a/docs/mp/openapi/openapi.adoc +++ b/docs/mp/openapi/openapi.adoc @@ -85,10 +85,12 @@ include::{incdir}/openapi.adoc[tag=usage-access-endpoint] include::{incdir}/openapi.adoc[tag=api] == Configuration -// -// Helidon OpenAPI configuration supports the following settings: -// -//include::{rootdir}/config/io_helidon_microprofile_openapi_MPOpenAPISupport.adoc[leveloffset=+1,tag=config] + +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 diff --git a/docs/se/openapi.adoc b/docs/se/openapi.adoc deleted file mode 100644 index ee7811d00e9..00000000000 --- a/docs/se/openapi.adoc +++ /dev/null @@ -1,123 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2019, 2023 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 -:toc: -:toc-placement: preamble -:description: Helidon SE OpenAPI Support -:keywords: helidon, se, openapi -:feature-name: OpenAPI -:rootdir: {docdir}/.. - -include::{rootdir}/includes/se.adoc[] - -== Contents - -- <> -- <> -- <> -- <> -- <> -- <> -- <> - -== Overview - -include::{rootdir}/includes/openapi/openapi.adoc[tag=overview] - -include::{rootdir}/includes/dependencies.adoc[] - -[source,xml] ----- - - io.helidon.openapi - helidon-openapi - ----- - -== Usage - -You can very simply add support for OpenAPI to your Helidon SE 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 - -==== Register `OpenAPISupport` in your application routing - -Helidon SE provides the link:{openapi-javadoc-base-url}/OpenAPISupport.html[`OpenAPISupport`] 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}/OpenAPISupport.Builder.html[`Builder`]. The xref:#register_openapisupport[example below] illustrates one way to do this. - -include::{rootdir}/includes/openapi/openapi.adoc[tag=furnish-openapi-info] - -==== Add OpenAPI dependency -If you implement either a model reader or a filter, add this dependency to your -`pom.xml`: - -[source,xml,subs="attributes+"] ----- - - org.eclipse.microprofile.openapi - microprofile-openapi-api - {microprofile-openapi-version} - ----- - -include::{rootdir}/includes/openapi/openapi.adoc[tag=usage-access-endpoint] - -== API - -include::{rootdir}/includes/openapi/openapi.adoc[tag=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}/OpenAPISupport.html[`OpenAPISupport`] or use its link:{openapi-javadoc-base-url}/OpenAPISupport.Builder.html[`Builder`] to create an instance of `OpenAPISupport`. Then add that instance to your application's routing. The <<#register_openapisupport,example>> below shows how to do this. - -== 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-tree-url}/examples/openapi[complete OpenAPI example] -based on the SE QuickStart sample app which includes a model reader and a filter. - -Most Helidon {flavor-uc} applications need only to create and register `OpenAPISupport`. - -[#register_openapisupport] -=== Register `OpenAPISupport` - -.Java Code to Register `OpenAPISupport` for Routing -[source,java] ----- -Config config = Config.create(); -return Routing.builder() - .register(JsonSupport.create()) - .register(OpenAPISupport.create(config)) // <1> - .register(health) // Health at "/health" - .register(metrics) // Metrics at "/metrics" - .register("/greet", greetService) - .build(); ----- -<1> Adds the `OpenAPISupport` service to your server. - -If you need more control over the `OpenAPISupport` instance, invoke `OpenAPISupport.builder()` to get an `OpenAPISupport.Builder` object and work with it. - -== Additional Information -include::{rootdir}/includes/openapi/openapi.adoc[tag=additional-building-jandex] \ No newline at end of file diff --git a/docs/se/openapi/openapi-ui.adoc b/docs/se/openapi/openapi-ui.adoc index 029f6930e21..262b80c3508 100644 --- a/docs/se/openapi/openapi-ui.adoc +++ b/docs/se/openapi/openapi-ui.adoc @@ -37,36 +37,41 @@ 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 `OpenAPISupport` service. +This dependency allows your application to create, configure, and register the `OpenApiFeature` service. include::{ui-inc}[tag=usage] == API -=== Creating `OpenAPISupport` with Automatic UI Behavior -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. +With the Helidon OpenAPI UI dependency in your `pom.xml` file, Helidon's 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 `OpenAPISupport` with automatic UI +.Create `OpenApiFeature` with automatic UI ---- Config config = Config.create(); // <1> -Config openApiConfig = config.get(OpenAPISupport.Builder.CONFIG_KEY)); // <2> - -OpenAPISupport openApiSupport = - OpenAPISupport.builder() - .config(openApiConfig) // <3> - .build(); +Config.global(config); + +WebServer server = WebServer.builder() + .config(config.get("server")) + .addFeature(OpenApiFeature.create(Config.global().get("openapi"))) // <2> + .routing(Main::routing) + .build() + .start(); ---- -<1> Load the configuration. -<2> Extract the `OpenAPISupport` configuration. -<3> Build the `OpenAPISupport` instance using the configuration. +<1> Load and set the global configuration. +<2> Add the OpenAPI feature to the server, configured using the `openapi` section of the configuration. -If your code invokes the `OpenAPISupport.Builder` `config` method, Helidon automatically applies the `ui` section of the `openapi` configuration to the UI. +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}/OpenApiUi.Builder.html[`OpenApiUi.Builder`] and invoke methods on it to set the UI behavior. -. Invoke the `ui` method on link:{openapi-javadoc-base-url}/io.helidon.openapi.OpenAPISupport.Builder.html[`OpenAPISupport.Builder`], passing the `OpenApiUi.Builder` you prepared above. +. Create an link:{javadoc-path}/OpenApiUi.Builder.html[`OpenApiUi.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.OpenApiFeature.Builder.html[`OpenApiFeature.Builder`], passing the `OpenApiUi` object you prepared above. The following example illustrates these steps, combining configuration with explicit programmatic settings. @@ -74,31 +79,34 @@ The following example illustrates these steps, combining configuration with expl .Create `OpenApiUi` and `OpenAPISupport` instances ---- Config config = Config.create(); // <1> -Config openApiConfig = config.get(OpenAPISupport.Builder.CONFIG_KEY)); // <2> - -OpenApiUi.Builder uiBuilder = - OpenApiUi.builder() // <3> - .webContext("/my-openapi-ui"); // <4> - -OpenAPISupport openApiSupport = - OpenAPISupport.builder() // <5> - .ui(uiBuilder) - .config(openApiConfig) // <6> - .build(); - - +Config.global(config); + +Config openApiConfig = Config.global().get("openapi"); // <2> +WebServer server = WebServer.builder() + .config(config.get("server")) + .addFeature(OpenApiFeature.builder() // <3> + .addService(OpenApiUi.builder() // <4> + .webContext("my-ui") // <5> + .config(openApiConfig.get("ui")) // <6> + .build()) // <7> + .config(openApiConfig) + .build()) // <8> + .routing(Main::routing) + .build() + .start(); ---- -<1> Load the configuration. -<2> Extract the `OpenAPISupport` configuration. -<3> Create the `OpenApiUi.Builder` instance. -<4> Explicitly set the web context where the UI should respond. -<5> 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. -<6> 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. +<1> Load and set global configuration. +<2> Extract the `openapi` config. +<3> Begin setting up the `OpenApiFeature` builder. +<4> Create the UI builder. +<5> Set UI behavior programmatically. +<6> Set additional UI behavior based on UI configuration. +<7> Build the `OpenApiUi` object. +<8> Build the `OpenApiFeature` object. + +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's `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. @@ -108,21 +116,6 @@ The `webContext(String)` method on `OpenApiUi.Builder` sets the web context whe 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. ==== -=== Registering `OpenAPISupport` -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. - -[source,java] -.Register services for routing ----- -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. - include::{ui-inc}[tag=config-intro] include::{ui-inc}[tag=config-details] diff --git a/docs/se/openapi/openapi.adoc b/docs/se/openapi/openapi.adoc index 6e8aeba2063..8f016faffb7 100644 --- a/docs/se/openapi/openapi.adoc +++ b/docs/se/openapi/openapi.adoc @@ -34,7 +34,6 @@ include::{rootdir}/includes/se.adoc[] - <> - <> - <> -- <> == Overview @@ -54,38 +53,24 @@ include::{rootdir}/includes/dependencies.adoc[] == Usage -You can very simply add support for OpenAPI to your Helidon SE 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. +=== 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. -=== Changing your application +=== Explicit Registration +To control the behavior of the OpenAPI feature programmatically, you can add and configure the OpenAPI feature explicitly as explained below. -==== Register `OpenAPISupport` in your application routing +==== Create and Register `OpenApiFeature` in your application -Helidon SE provides the link:{javadoc-path}/OpenAPISupport.html[`OpenAPISupport`] 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:{javadoc-path}/OpenAPISupport.Builder.html[`Builder`]. The xref:#register_openapisupport[example below] illustrates one way to do this. +Helidon SE provides the link:{openapi-javadoc-base-url}/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}/OpenApiFeature.Builder.html[`Builder`]. The xref:#register_openapifeature[example below] illustrates one way to do this. -include::{incdir}/openapi.adoc[tag=furnish-openapi-info] - -==== Add OpenAPI dependency -If you implement either a model reader or a filter, add this dependency to your -`pom.xml`: -[source,xml,subs="attributes+"] ----- - - org.eclipse.microprofile.openapi - microprofile-openapi-api - {microprofile-openapi-version} - ----- +include::{incdir}/openapi.adoc[tag=furnish-openapi-info] include::{incdir}/openapi.adoc[tag=usage-access-endpoint] == API -include::{incdir}/openapi.adoc[tag=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:{javadoc-path}/OpenAPISupport.html[`OpenAPISupport`] or use its link:{javadoc-base}/OpenAPISupport.Builder.html[`Builder`] to create an instance of `OpenAPISupport`. Then add that instance to your application's routing. The <<#register_openapisupport,example>> below shows how to do this. +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}/OpenApiFeature.html[`OpenApiFeature`] or use its link:{openapi-javadoc-base-url}/OpenApiFeature.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 @@ -99,28 +84,27 @@ include::{rootdir}/config/io_helidon_openapi_OpenApiFeature.adoc[leveloffset=+1, == Examples Helidon SE provides a link:{helidon-github-tree-url}/examples/openapi[complete OpenAPI example] -based on the SE QuickStart sample app which includes a model reader and a filter. +based on the SE QuickStart sample app. -Most Helidon {flavor-uc} applications need only to create and register `OpenAPISupport`. +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_openapisupport] -=== Register `OpenAPISupport` +[#register_openapifeature] +=== Register `OpenApiFeature` explicitly -.Java Code to Register `OpenAPISupport` for Routing +.Java Code to Create and Register `OpenAPISupport` [source,java] ---- -Config config = Config.create(); -return Routing.builder() - .register(JsonSupport.create()) - .register(OpenAPISupport.create(config)) // <1> - .register(health) // Health at "/health" - .register(metrics) // Metrics at "/metrics" - .register("/greet", greetService) - .build(); +Config config = Config.create(); // <1> +Config.global(config); + +WebServer server = WebServer.builder() + .config(config.get("server")) + .addFeature(OpenApiFeature.create(Config.global().get("openapi"))) // <2> + .routing(Main::routing) + .build() + .start(); ---- -<1> Adds the `OpenAPISupport` service to your server. - -If you need more control over the `OpenAPISupport` instance, invoke `OpenAPISupport.builder()` to get an `OpenAPISupport.Builder` object and work with it. +<1> Initializes the global `Config` instance from the default configuration. +<2> Adds the `OpenApiFeature` service to your server using the `openapi` section from configuration. -== Additional Information -include::{incdir}/openapi.adoc[tag=additional-building-jandex] \ No newline at end of file +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. \ No newline at end of file