Skip to content

Commit f52a7b5

Browse files
marceljkmarceljk
committed
adjust generator config
- add custom README.mustache
1 parent af712f4 commit f52a7b5

File tree

5 files changed

+222
-3
lines changed

5 files changed

+222
-3
lines changed

‎openapi-generator-config-java.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
templateDir: templates/java
12
additionalProperties:
23
artifactUrl: https://github.com/stackitcloud/stackit-sdk-java
34
developerName: STACKIT Developer Tools

‎scripts/generate-sdk/.openapi-generator-ignore-java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@ git_push.sh
33
.gitignore
44
api/openapi.yaml
55
tox.ini
6-
**/.github/**
6+
**/.github/**
7+
**/AndroidManifest.xml

‎scripts/generate-sdk/languages/java.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,8 +112,8 @@ generate_java_sdk() {
112112
--git-host ${GIT_HOST} \
113113
--git-user-id ${GIT_USER_ID} \
114114
--git-repo-id ${GIT_REPO_ID} \
115-
--global-property apis,models,modelTests=false,modelDocs=false,apiDocs=false,apiTests=false,supportingFiles \
116-
--additional-properties=artifactId="stackit-${service}",artifactDescription="${SERVICE_DESCRIPTION}",invokerPackage="cloud.stackit.${service}",modelPackage="cloud.stackit.${service}.model",apiPackage="cloud.stackit.${service}.api" >/dev/null \
115+
--global-property apis,models,modelTests=false,apiTests=false,supportingFiles \
116+
--additional-properties=artifactId="stackit-sdk-${service}",artifactDescription="${SERVICE_DESCRIPTION}",invokerPackage="cloud.stackit.sdk.${service}",modelPackage="cloud.stackit.sdk.${service}.model",apiPackage="cloud.stackit.sdk.${service}.api" >/dev/null \
117117
--http-user-agent stackit-sdk-java/"${service}" \
118118
--config openapi-generator-config-java.yml
119119

‎templates/java/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Java templates
2+
3+
This folder contains only our customized Java templates. Beside these customized templates,
4+
the original templates of openapi-generator for Java are used. These can be found in the
5+
official GitHub repo of the [openapi-generator](https://github.com/OpenAPITools/openapi-generator/tree/v7.14.0/modules/openapi-generator/src/main/resources/Java).
6+
7+
If you need to change something in the Java Generator, try always first to add
8+
[user-defined templates](https://openapi-generator.tech/docs/customization#user-defined-templates),
9+
instead of overwriting existing templates. These ensure an easier upgrade process, to newer
10+
versions of the openapi-generator.
11+
12+
If it's required to customize the original templates, you can copy them into this directory.
13+
Try to minimize the customization as much as possible, to ensure, that we can easily upgrade
14+
to newer versions in the future.

‎templates/java/README.mustache‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# {{artifactId}}
2+
3+
{{appName}}
4+
5+
- API version: {{appVersion}}
6+
7+
{{{appDescriptionWithNewLines}}}
8+
9+
{{#infoUrl}}
10+
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
11+
{{/infoUrl}}
12+
13+
This package is part of the STACKIT Java SDK. For additional information, please visit the [GitHub repository](https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}) of the SDK.
14+
15+
16+
## Requirements
17+
18+
Building the API client library requires:
19+
20+
1. Java 1.8+
21+
{{#jersey2}}
22+
2. Maven (3.8.3+)/Gradle (7.2+)
23+
{{/jersey2}}
24+
{{^jersey2}}
25+
2. Maven/Gradle
26+
{{/jersey2}}
27+
28+
## Installation
29+
30+
To install the API client library to your local Maven repository, simply execute:
31+
32+
```shell
33+
mvn clean install
34+
```
35+
36+
To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
37+
38+
```shell
39+
mvn clean deploy
40+
```
41+
42+
Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
43+
44+
### Maven users
45+
46+
Add this dependency to your project's POM:
47+
48+
```xml
49+
<dependency>
50+
<groupId>{{{groupId}}}</groupId>
51+
<artifactId>{{{artifactId}}}</artifactId>
52+
<version>{{{artifactVersion}}}</version>
53+
<scope>compile</scope>
54+
</dependency>
55+
```
56+
57+
### Gradle users
58+
59+
Add this dependency to your project's build file:
60+
61+
```groovy
62+
repositories {
63+
mavenCentral() // Needed if the '{{{artifactId}}}' jar has been published to maven central.
64+
mavenLocal() // Needed if the '{{{artifactId}}}' jar has been published to the local maven repo.
65+
}
66+
67+
dependencies {
68+
implementation "{{{groupId}}}:{{{artifactId}}}:{{{artifactVersion}}}"
69+
}
70+
```
71+
72+
### Others
73+
74+
At first generate the JAR by executing:
75+
76+
```shell
77+
mvn clean package
78+
```
79+
80+
Then manually install the following JARs:
81+
82+
- `target/{{{artifactId}}}-{{{artifactVersion}}}.jar`
83+
- `target/lib/*.jar`
84+
85+
{{#jersey2}}
86+
## Usage
87+
88+
To add a HTTP proxy for the API client, use `ClientConfig`:
89+
```java
90+
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
91+
import org.glassfish.jersey.apache.connector.ApacheConnectorProvider;
92+
import org.glassfish.jersey.client.ClientConfig;
93+
import org.glassfish.jersey.client.ClientProperties;
94+
import {{{invokerPackage}}}.*;
95+
import {{{package}}}.{{{classname}}};
96+
97+
...
98+
99+
ApiClient defaultClient = Configuration.getDefaultApiClient();
100+
ClientConfig clientConfig = defaultClient.getClientConfig();
101+
clientConfig.connectorProvider(new ApacheConnectorProvider());
102+
clientConfig.property(ClientProperties.PROXY_URI, "http://proxy_url_here");
103+
clientConfig.property(ClientProperties.PROXY_USERNAME, "proxy_username");
104+
clientConfig.property(ClientProperties.PROXY_PASSWORD, "proxy_password");
105+
defaultClient.setClientConfig(clientConfig);
106+
107+
{{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
108+
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
109+
```
110+
111+
{{/jersey2}}
112+
## Getting Started
113+
114+
Please follow the [installation](#installation) instruction and execute the following Java code:
115+
116+
```java
117+
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
118+
import {{{invokerPackage}}}.*;
119+
import {{{invokerPackage}}}.auth.*;
120+
import {{{modelPackage}}}.*;
121+
import {{{package}}}.{{{classname}}};
122+
123+
public class {{{classname}}}Example {
124+
125+
public static void main(String[] args) {
126+
ApiClient defaultClient = Configuration.getDefaultApiClient();
127+
defaultClient.setBasePath("{{{basePath}}}");
128+
{{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}{{#isBasicBasic}}
129+
// Configure HTTP basic authorization: {{{name}}}
130+
HttpBasicAuth {{{name}}} = (HttpBasicAuth) defaultClient.getAuthentication("{{{name}}}");
131+
{{{name}}}.setUsername("YOUR USERNAME");
132+
{{{name}}}.setPassword("YOUR PASSWORD");{{/isBasicBasic}}{{#isBasicBearer}}
133+
// Configure HTTP bearer authorization: {{{name}}}
134+
HttpBearerAuth {{{name}}} = (HttpBearerAuth) defaultClient.getAuthentication("{{{name}}}");
135+
{{{name}}}.setBearerToken("BEARER TOKEN");{{/isBasicBearer}}{{/isBasic}}{{#isApiKey}}
136+
// Configure API key authorization: {{{name}}}
137+
ApiKeyAuth {{{name}}} = (ApiKeyAuth) defaultClient.getAuthentication("{{{name}}}");
138+
{{{name}}}.setApiKey("YOUR API KEY");
139+
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
140+
//{{{name}}}.setApiKeyPrefix("Token");{{/isApiKey}}{{#isOAuth}}
141+
// Configure OAuth2 access token for authorization: {{{name}}}
142+
OAuth {{{name}}} = (OAuth) defaultClient.getAuthentication("{{{name}}}");
143+
{{{name}}}.setAccessToken("YOUR ACCESS TOKEN");{{/isOAuth}}{{#isHttpSignature}}
144+
// Configure HTTP signature authorization: {{{name}}}
145+
HttpSignatureAuth {{{name}}} = (HttpSignatureAuth) defaultClient.getAuthentication("{{{name}}}");
146+
// All the HTTP signature parameters below should be customized to your environment.
147+
// Configure the keyId
148+
{{{name}}}.setKeyId("YOUR KEY ID");
149+
// Configure the signature algorithm
150+
{{{name}}}.setSigningAlgorithm(SigningAlgorithm.HS2019);
151+
// Configure the specific cryptographic algorithm
152+
{{{name}}}.setAlgorithm(Algorithm.ECDSA_SHA256);
153+
// Configure the cryptographic algorithm parameters, if applicable
154+
{{{name}}}.setAlgorithmParameterSpec(null);
155+
// Set the cryptographic digest algorithm.
156+
{{{name}}}.setDigestAlgorithm("SHA-256");
157+
// Set the HTTP headers that should be included in the HTTP signature.
158+
{{{name}}}.setHeaders(Arrays.asList("date", "host"));
159+
// Set the private key used to sign the HTTP messages
160+
{{{name}}}.setPrivateKey();{{/isHttpSignature}}
161+
{{/authMethods}}
162+
{{/hasAuthMethods}}
163+
164+
{{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
165+
{{#allParams}}
166+
{{{dataType}}} {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
167+
{{/allParams}}
168+
try {
169+
{{#returnType}}{{{.}}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}});{{#returnType}}
170+
System.out.println(result);{{/returnType}}
171+
} catch (ApiException e) {
172+
System.err.println("Exception when calling {{{classname}}}#{{{operationId}}}");
173+
System.err.println("Status code: " + e.getCode());
174+
System.err.println("Reason: " + e.getResponseBody());
175+
System.err.println("Response headers: " + e.getResponseHeaders());
176+
e.printStackTrace();
177+
}
178+
}
179+
}
180+
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
181+
```
182+
183+
## Documentation for API Endpoints
184+
185+
All URIs are relative to *{{basePath}}*
186+
187+
Class | Method | HTTP request | Description
188+
------------ | ------------- | ------------- | -------------
189+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{commonPath}}{{path}} | {{summary}}
190+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
191+
192+
## Documentation for Models
193+
194+
{{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
195+
{{/model}}{{/models}}
196+
197+
<a id="documentation-for-authorization"></a>
198+
199+
## Recommendation
200+
201+
It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.
202+
203+
## Author

0 commit comments

Comments
 (0)