From 3f5474218d216524c16f5df423314577c783787d Mon Sep 17 00:00:00 2001 From: Roshin Rajan Panackal Date: Wed, 28 Jan 2026 17:17:12 +0100 Subject: [PATCH] Update generation of openapi client docs --- .../features/rest/generate-rest-client.mdx | 123 +++++++++++++++--- docs-java/features/rest/overview.mdx | 1 + 2 files changed, 107 insertions(+), 17 deletions(-) diff --git a/docs-java/features/rest/generate-rest-client.mdx b/docs-java/features/rest/generate-rest-client.mdx index f767a134b23..3cb04df73bb 100644 --- a/docs-java/features/rest/generate-rest-client.mdx +++ b/docs-java/features/rest/generate-rest-client.mdx @@ -30,8 +30,31 @@ However, languages that use non-latin characters, specifically languages that re ::: +Starting from version 5.26.0, the OpenAPI generator supports two HTTP client libraries: **Spring RestTemplate (default)** and **Apache HttpClient 5**. +To use Apache HttpClient, checkout [Declaring Dependencies](#declaring-dependencies) and plugin configuration in section [Choosing the HTTP Client Library](#choosing-the-http-client-library). + +## Declaring Dependencies + The generated Java classes need the following dependency to be present in your project: + + + +```xml + + com.sap.cloud.sdk.datamodel + openapi-core-apache + +``` + +To use the generated client library, either the SAP Cloud SDK BOM should be part of your project's `` section, or the version for the `openapi-core-apache` artifact must be mentioned explicitly here. + + + + ```xml com.sap.cloud.sdk.datamodel @@ -41,10 +64,17 @@ The generated Java classes need the following dependency to be present in your p To use the generated client library, either the SAP Cloud SDK BOM should be part of your project's `` section, or the version for the `openapi-core` artifact must be mentioned explicitly here. + + + ## Generated Java Classes and Usage In this section, we will explain how to use the OpenAPI Generator Maven Plugin. -A sample result can be seen in our [open-source public repository](https://github.com/SAP/cloud-sdk-java/tree/main/datamodel/openapi/openapi-api-sample) with the _SodaStore_ OpenAPI. +A sample result can be seen in our [open-source public repository](https://github.com/SAP/cloud-sdk-java/tree/main/datamodel/openapi/openapi-api-sample) with the _SodaStore_ OpenAPI: + +- [Apache HttpClient sample](https://github.com/SAP/cloud-sdk-java/tree/main/datamodel/openapi/openapi-api-apache-sample) +- [Spring RestTemplate sample](https://github.com/SAP/cloud-sdk-java/tree/main/datamodel/openapi/openapi-api-sample) + Given the `sodastore.json` as input the following service classes get generated: ``` @@ -63,7 +93,50 @@ openapi-api-sample/ The generated API can be used like the following: + + + + ```java +import com.sap.cloud.sdk.services.openapi.apache.apiclient.ApiClient; + +Destination destination; + +// create the service with a destination +SodasApi service = new SodasApi(destination); + +// create an entity object +SodaWithId soda = new SodaWithId().id(0L).name("Cola").brand("SAP-Cola").quantity(100).price(1.5f); + +// execute request for entity update +service.sodasPut(soda); +``` + +Services can be instantiated in different ways: + +```java +new SodasApi( ) +new SodasApi( Destination ) +new SodasApi( new ApiClient() ) +new SodasApi( new ApiClient(Destination) ) +new SodasApi( new ApiClient(ClosableHttpClient) ) +``` + +The [`ApiClient`](https://sap.github.io/cloud-sdk/java-api/v5/com/sap/cloud/sdk/services/openapi/apache/apiclient/ApiClient.html) allows for versatile customization. +Default service base-path, object mapper and file download location can be assigned. +When using `Destination`, the base-path is extracted automatically from the provided destination. +Alternatively, the `ClosableHttpClient` based constructor can be used for fully customized requests. + + + + + +```java +import com.sap.cloud.sdk.services.openapi.apiclient.ApiClient; + Destination destination; // create the service with a destination @@ -90,6 +163,9 @@ Default service base-path, user-agent and request headers can be assigned. When using `Destination` these parameters are extracted automatically from the provided destination. Alternatively, the `RestTemplate` based constructor can be used for fully customized requests. + + + ## Using the OpenAPI Generator Maven Plugin To use the Maven plugin following XML snippet should be added to the POM file of your project: @@ -148,6 +224,18 @@ Please note that the version of the above plugin must be specified at least once Also, the version of the plugin should be the same as of the SAP Cloud SDK. We recommend using a Maven property for defining the version of both the Maven plugin and the SAP Cloud SDK BOM. +### Choosing the HTTP Client Library + +To use Apache HttpClient instead of the Spring RestTemplate, you need to add the following configuration within plugin `` tag: + +```xml + + apache-httpclient + +``` + +By leaving out the above configuration, the generator defaults to using Spring RestTemplate as the HTTP client library. + ### Using the Plugin from the Command Line The maven plugin can also be invoked without a project from the command line using `-D` parameter flags, for example: @@ -206,22 +294,23 @@ You can pass arbitrary additional configuration properties to the underlying [op The complete list of available parameters with their description is as follows: -| Parameter | Default | Required | Description | -| :----------------------------- | :--------: | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `` | - | Yes | Location of the OpenAPI specification file | -| `` | - | Yes | Output directory for generated sources | -| `` | - | Yes | Package name for the generated API classes | -| `` | - | Yes | Package name for the generated Model classes | -| `` | `True` | No | Determines whether to generate API classes | -| `` | `True` | No | Determines whether to generate Model classes | -| `` | `False` | No | Determines whether to delete the output directory before running the generator | -| `` | `released` | No | Defines the maturity of the OpenAPI for which Java classes are generated. Possible values are `released` and `beta`. Please note if you define it as `beta` then [@Beta annotations](https://www.javadoc.io/doc/com.google.guava/guava/latest/com/google/common/annotations/Beta.html) are added to the generated classes which indicate that they are in an experimental state | -| `` | `NONE` | No | Adds the generated sources to the compilation or test phase. Respective values are `COMPILE` and `TEST_COMPILE` | -| `` | `null` | No | Copyright header to be added at the top of generated files | -| `` | `False` | No | Run the generator with verbose output | -| `` | `False` | No | Add the SAP copyright header (overrides `copyrightHeader`) | -| `` | `False` | No | Defines whether to enable processing of anyOf/oneOf keywords during client generation | -| `` | `[]` | No | Defines a map of key-value pairs that will be passed to the Java generator. E.g. `value` | +| Parameter | Default | Required | Description | +| :----------------------------- | :------------: | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `` | - | Yes | Location of the OpenAPI specification file | +| `` | - | Yes | Output directory for generated sources | +| `` | - | Yes | Package name for the generated API classes | +| `` | - | Yes | Package name for the generated Model classes | +| `` | `True` | No | Determines whether to generate API classes | +| `` | `True` | No | Determines whether to generate Model classes | +| `` | `False` | No | Determines whether to delete the output directory before running the generator | +| `` | `released` | No | Defines the maturity of the OpenAPI for which Java classes are generated. Possible values are `released` and `beta`. Please note if you define it as `beta` then [@Beta annotations](https://www.javadoc.io/doc/com.google.guava/guava/latest/com/google/common/annotations/Beta.html) are added to the generated classes which indicate that they are in an experimental state | +| `` | `NONE` | No | Adds the generated sources to the compilation or test phase. Respective values are `COMPILE` and `TEST_COMPILE` | +| `` | `null` | No | Copyright header to be added at the top of generated files | +| `` | `False` | No | Run the generator with verbose output | +| `` | `False` | No | Add the SAP copyright header (overrides `copyrightHeader`) | +| `` | `False` | No | Defines whether to enable processing of anyOf/oneOf keywords during client generation | +| `` | `[]` | No | Defines a map of key-value pairs that will be passed to the Java generator. E.g. `value` | +| `` | `resttemplate` | No | Defines the http client library to use and lives within ``. Only valid values are `resttemplate` and `apache-httpclient`. | ## Customize Java Class and Method Names with OpenAPI Vendor Extensions diff --git a/docs-java/features/rest/overview.mdx b/docs-java/features/rest/overview.mdx index f847cacaf4c..59612fe0507 100644 --- a/docs-java/features/rest/overview.mdx +++ b/docs-java/features/rest/overview.mdx @@ -35,3 +35,4 @@ If you encounter any problems or errors with OpenAPI tooling give us feedback vi - We take care of change management by continuously updating, integrating, and shipping the latest version of services that we release. - Our documentation is written by developers for developers. We keep it relevant and up to date. +- Starting from version 5.26.0, you can choose between Apache HttpClient and Spring RestTemplate as the underlying HTTP client library, giving you flexibility based on your application's requirements.