Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/main' into 6456_webclient_doc_…
Browse files Browse the repository at this point in the history
…part2_4.x
  • Loading branch information
klustria committed Oct 19, 2023
2 parents 77f29c2 + 54dade6 commit d3ea4cc
Show file tree
Hide file tree
Showing 10 changed files with 395 additions and 759 deletions.
18 changes: 11 additions & 7 deletions docs/includes/openapi/openapi-ui.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -59,15 +63,15 @@ include::{rootdir}/includes/dependencies.adoc[]
[source,xml,subs=+macros]
----
<dependency>
<groupId>io.helidon.openapi</groupId>
<artifactId>helidon-openapi-ui</artifactId>
<groupId>io.helidon.integrations.openapi-ui</groupId>
<artifactId>helidon-integrations-openapi-ui</artifactId>
ifdef::mp-flavor[ <scope>runtime</scope>]
</dependency>
----
And add a runtime dependency on the SmallRye UI.
[source,xml,subs=+macros]
[source,xml]
----
<dependency>
<groupId>io.smallrye</groupId>
Expand All @@ -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 <<API,API>> 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 <<API,API>> 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`.
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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.
Expand Down
75 changes: 37 additions & 38 deletions docs/includes/openapi/openapi.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand All @@ -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[]
Expand All @@ -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.
Expand Down Expand 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`
Expand Down
38 changes: 21 additions & 17 deletions docs/mp/guides/health.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////////

Copyright (c) 2019, 2022 Oracle and/or its affiliates.
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.
Expand Down Expand Up @@ -51,8 +51,7 @@ mvn -U archetype:generate -DinteractiveMode=false \
=== Using the Built-In Health Checks
Helidon has a set of built-in health checks that are automatically enabled to report various
health check statuses that are commonly used:
Helidon has a set of built-in health checks:
* deadlock detection
* available disk space
Expand All @@ -61,10 +60,14 @@ health check statuses that are commonly used:
The following example will demonstrate how to use the built-in health checks. These examples are all executed
from the root directory of your project (helidon-quickstart-mp).
[source,xml]
.Include dependency for the built-in health checks
include::{rootdir}/mp/health.adoc[tag=built-in-health-checks-depc]
[source,bash]
.Build the application, skipping unit tests, then run it:
.Build the application then run it:
----
mvn package -DskipTests=true
mvn package
java -jar target/helidon-quickstart-mp.jar
----
Expand Down Expand Up @@ -488,9 +491,9 @@ The example below will change the root path.
.Create a file named `application.yaml` in the `resources` directory with the following contents:
----
health:
web-context: "myhealth" // <1>
endpoint: "/myhealth" // <1>
----
<1> The web-context specifies a new root path for the health endpoint.
<1> The `endpoint` settings specifies the root path for the health endpoint.
[source,bash]
.Build and run the application, then verify that the health endpoint is using the new `/myhealth` root:
Expand All @@ -507,20 +510,21 @@ The following example will change the root path and the health port.
.Update application.yaml to use a different port and root path for the health endpoint:
----
server:
port: 8080 // <1>
host: "localhost"
port: 8080 // <1>
sockets:
health: // <2>
port: 8081 // <3>
bind-address: "localhost"
- name: "admin" // <2>
port: 8081 // <3>
features:
observe:
sockets: "admin" // <4>
health:
routing: "health" // <4>
web-context: "myhealth"
endpoint: "/myhealth" // <5>
----
<1> The default port for the application.
<2> The name of the new socket, it can be any name, this example uses `health`.
<3> The port for the new health socket.
<4> The health endpoint routing uses the new socket `health`.
<2> The name of the new socket, it can be any name, this example uses `admin`.
<3> The port for the `admin` socket.
<4> The health endpoint, as part of Helidon's observability support, uses the socket `admin`.
[source,bash]
Expand Down
22 changes: 12 additions & 10 deletions docs/mp/health.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -79,14 +79,15 @@ If full control over the dependencies is required, and you want to minimize the
To enable built-in health checks add the following dependency
(or use the xref:introduction/microprofile.adoc[helidon-microprofile bundle] )
//tag::built-in-health-checks-depc[]
[source,xml]
----
<dependency>
<groupId>io.helidon.health</groupId>
<artifactId>helidon-health-checks</artifactId>
</dependency>
----
//end::built-in-health-checks-depc[]
== Usage
Expand Down Expand Up @@ -154,7 +155,7 @@ The class responsible for configuration is:
include::{rootdir}/config/io_helidon_webserver_observe_health_HealthObserver.adoc[leveloffset=+1,tag=config]
Current properties may be set in `application.yaml` or in `microprofile-config.properties` with `health` prefix.
Properties may be set in `application.yaml` or in `microprofile-config.properties`, in both cases using the `health` prefix.
For example, you can specify a custom port and root context for the root health endpoint path.
However, you cannot use different ports, such as http://localhost:8080/myhealth and http://localhost:8081/myhealth/live.
Expand All @@ -163,18 +164,18 @@ The example below will change the root path.
[source,properties]
.Create a file named `microprofile-config.properties` in the `resources/META-INF` directory with the following contents:
----
health.web-context=myhealth #<1>
health.endpoint=/myhealth #<1>
----
<1> The web-context specifies a new root path for the health endpoint.
<1> The `endpoint` setting specifies the root path for the health endpoint.
== Examples
Generate Helidon MP Quickstart project following these xref:guides/quickstart.adoc[Instruction]
Generate Helidon MP Quickstart project following these xref:guides/quickstart.adoc[instructions].
=== Using the Built-In Health Checks
Helidon has a set of built-in health checks that are enabled to report various
health check statuses that are commonly used:
Helidon has a set of built-in health checks that can report various
conditions:
* deadlock detection
* available disk space
Expand All @@ -183,6 +184,10 @@ health check statuses that are commonly used:
The following example will demonstrate how to use the built-in health checks. These examples are all executed
from the root directory of your project (helidon-quickstart-mp).
[source,xml]
.Include the built-in health checks dependency in your `pom.xml`:
include::{rootdir}/mp/health.adoc[tag=built-in-health-checks-depc]
[source,bash]
.Build the application, then run it:
----
Expand Down Expand Up @@ -282,9 +287,6 @@ curl http://localhost:8080/health/live
}
----
Full example code is available link:{helidon-github-tree-url}/examples/microprofile[here].
=== Custom Readiness Health Checks
You can add a readiness check to indicate that the application is ready to be used. In this
Expand Down
10 changes: 6 additions & 4 deletions docs/mp/openapi/openapi.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit d3ea4cc

Please sign in to comment.