Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
///////////////////////////////////////////////////////////////////////////////
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.
///////////////////////////////////////////////////////////////////////////////
// tag::preamble[]
:description: Helidon {flavor-uc} OpenAPI Generator
:keywords: helidon, {flavor-lc}, openapi, generator
:feature-name: Helidon {flavor-uc} OpenAPI Generator
// DO NOT CHANGE THE FOLLOWING - it's used as a minimum release that will not normally change with new releases of the OpenAPI generator
:first-version-with-strong-helidon-support: 6.2.1
// Update the following when it is convenient to keep pace with the latest releases of the OpenAPITools generator
// end::preamble[]
// tag::intro[]
== Contents
- <>
- <>
- <>
- <>
- <>
== Overview
The link:{openapi-spec-url}[OpenAPI specification] provides a standard way to express RESTful APIs.
Separately, the link:{openapi-generator-tool-site-url}[OpenAPI generator] project has created a powerful code generator tool which accepts an OpenAPI document and generates client and server code for many languages and frameworks. The Helidon team contributes to this tool to ensure that it provides strong support for Helidon {flavor-uc} clients and servers.
As a result, you can use the generator to create code that fits smoothly into your Helidon applications.
The OpenAPI generator release {first-version-with-strong-helidon-support} gained particularly strong support for Helidon.
This document applies to that release and later ones.
In the vocabulary of the tool, there are two _generators_ for Helidon:
* `java-helidon-client` (hereafter the Helidon client generator)
* `java-helidon-server` (hereafter the Helidon server generator).
Each of these generators supports two _libraries_:
* `mp` - for Helidon MP code generation
* `se` - for Helidon SE code generation
Use the Helidon _client_ generator and its `{flavor-lc}` library to create a
ifdef::mp-flavor[]
xref:{helidon-client-xref}[Helidon MicroProfile REST client].
endif::mp-flavor[]
ifdef::se-flavor[]
Helidon SE client based on xref:{helidon-client-xref}[Helidon WebClients].
endif::se-flavor[]
The resulting client library works with any server that implements the API declared in the OpenAPI document you specified when you ran the generator.
The client library provides an abstraction similar to remote procedure calls (RPC).
To access a remote service that implements the endpoints declared in the OpenAPI document, your code uses the generated client library first to establish a connection to the remote service and then to call remote service endpoints by invoking local methods passing POJO business objects or Java types as arguments.
Use the tool's Helidon _server_ generator and its `{flavor-lc}` library to create server endpoint stubs for a Helidon {flavor-uc} service. You build on these stubs by extending a generated class or implementing a generated interface, adding your specific business logic to finish the implementation of the endpoints. The combination of the generated server code plus Helidon {flavor-uc} underneath it allows you to focus on the business details instead of resource boilerplate.
You can run the OpenAPI generators in three ways:
// tag::three-ways-to-run[]
* using the OpenAPI generator CLI
* using the OpenAPI generator Maven plug-in
* using the online OpenAPI generator website
// end::three-ways-to-run[]
The rest of this document walks you through <> each technique and how to <> the generators to produce the code you want.
// end::intro[]
// tag::coords[]
== Maven Coordinates
Your project does not need any dependencies on the OpenAPI generator.
To use the OpenAPI generator plug-in to generate or regenerate files during your project build, add the following to your project's `pom.xml` file to declare the plug-in. Choose whichever version of the generator plug-in meets your needs as long as it is at least {first-version-with-strong-helidon-support}.
[source,xml,subs="+attributes,+macros"]
.Declaring the OpenAPI Generator Plug-in
----
{openapi-generator-version}
...
...
...
org.openapitoolsopenapi-generator-maven-plugin++${openapi-generator-version}++
...
...
----
A <> describes how to invoke the plug-in during your build.
// end::coords[]
// tag::config[]
== Configuration
The OpenAPI generators support a substantial, powerful, and sometimes bewildering group of configuration settings.
For complete lists see these pages:
[[links-to-settings]]
* link:{openapi-generator-tool-docs-url}/usage.md#generate[generic options]
* link:{openapi-generator-tool-generators-docs-url}/java-helidon-client.md[Helidon client generator options] and
* link:{openapi-generator-tool-generators-docs-url}/java-helidon-server.md[Helidon server generator options]
The OpenAPI generator loosely divides its settings into three types:
* _global properties_
+
These settings generally govern the overall behavior of the tool, regardless of which specific generator you use.
+
For the CLI, use the common option style:
+
`-i petstore.yaml`
+
`--input-spec petstore.yaml`
+
For the Maven plug-in, use elements within the `` section of the plug-in:
+
[source,xml]
----
petstore.yaml
----
* _options_
+
These settings typically affect how particular generators operate.
+
For the CLI, specify config options as additional properties:
+
`--additional-properties=groupId=com.mycompany.test,artifactId=my-example`
+
or
+
[source,bash]
----
-p groupId=com.mycompany.test
-p artifactId=my-example
----
+
For the Maven plug-in, use the `` section within ``:
+
[source,xml]
----
...
com.mycompany.testmy-example
...
----
* _additional properties_
+
Settings in this category typically are passed to the templates used in generating the files, although generators can use additional properties in deciding how to generate the files.
+
For the CLI:
+
`--additional-properties "useAbstractClasses=false,returnResponse=true"`
+
or
+
[source,bash]
----
-p useAbstractClasses=false
-p returnResponse=true
----
+
For the Maven plug-in, use an `` section within the `` section for the plug-in:
+
[source,xml]
----
....
useAbstractClasses=falsereturnResponse=true
----
Keep this distinction among global options, config options, and additional properties in mind so you know how to express the configuration you want.
The <> to the lists of configuration options for the Helidon generators groups options and additional properties in separate tables.
The next few sections describe, in turn, required settings, settings we recommend, and other common settings most developers will want to use.
=== Required Settings
You must specify the following options:
.Required OpenAPI Generator Options
[cols="4,1,4,6,5"]
|===
|Option | Short Option |Plug-in Setting | Description | Values
|`--inputSpec`
|`-i`
|``
|Path to the OpenAPI document defining the REST API
|
|`--generatorName`
|`-g`
|``
| Generator you want to use (`java-helidon-server` or `java-helidon-client`)
| `java-helidon-server` +
`java-helidon-client`
|`--library` +
``
| {nbsp}
|Library you want to use
|`mp` +
`se`
|===
=== Recommended Settings for the OpenAPI Generator
Your project might have different needs, but in general we advise developers to use the following settings when using the OpenAPI generator.
.Recommended OpenAPI Generator Additional Properties
[cols="3,6,5"]
|===
| Property | Description | Default
| `apiPackage`
| Name of the package for generated API interfaces/classes
| `org.openapitools.server.api` or +
`org.openapitools.client.api`
| `modelPackage`
| Name of the package for generated model (POJO) classes
| `org.openapitools.server.model` or +
`org.openapitools.client.model`
| `invokerPackage`
| Name of the package for generated driver classes
| `org.openapitools.server` or +
`org.openapitools.client`
| `groupId`
| Group ID in the generated `pom.xml`
| `org.openapitools`
| `artifactId`
| Artifact ID in the generated `pom.xml`
| `openapi-java-server` or +
`openapi-java-client`
| `artifactVersion`
| Artifact version in the generated `pom.xml`
| `1.0.0`
|===
[NOTE]
The next table contains recommendations only for using the OpenAPI generator plug-in (not for using the CLI).
.Recommended OpenAPI Generator Plug-in Options
[cols="4,8,5"]
|===
|Plug-in Option | Description |Default
|`
