Skip to content

Commit a82b090

Browse files
danuwdanuw
authored
Merge pull request #471 from YaSuenag/pr/generate-java-webapi-client
Add GHA workflow for generating WebAPI client library for Java
2 parents e7ba0ff + 6ee03f6 commit a82b090

File tree

134 files changed

+256
-23337
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

134 files changed

+256
-23337
lines changed

‎.github/workflows/4-release.yaml

+33
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,17 @@ env:
99
IMAGE_NAME: ${{ github.repository }}
1010

1111
jobs:
12+
detect-current-api-version:
13+
uses: ./.github/workflows/detect-webapi-version.yaml
14+
with:
15+
# We cannot use environment variables here due to workflow limitation.
16+
# https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/reusing-workflows#limitations
17+
registry: ghcr.io
18+
image-repo: ${{ github.repository }}
19+
1220
publish-container-image:
1321
runs-on: ubuntu-latest
22+
needs: detect-current-api-version
1423
permissions:
1524
packages: write
1625
steps:
@@ -39,3 +48,27 @@ jobs:
3948
tags: ${{ steps.meta.outputs.tags }}
4049
labels: ${{ steps.meta.outputs.labels }}
4150
provenance: false
51+
52+
detect-newer-api-version:
53+
needs: publish-container-image
54+
uses: ./.github/workflows/detect-webapi-version.yaml
55+
with:
56+
# We cannot use environment variables here due to workflow limitation.
57+
# https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/reusing-workflows#limitations
58+
registry: ghcr.io
59+
image-repo: ${{ github.repository }}
60+
61+
generate-webapi-clients:
62+
needs:
63+
- detect-current-api-version
64+
- detect-newer-api-version
65+
if: ${{ needs.detect-current-api-version.outputs.apiver != needs.detect-newer-api-version.outputs.apiver }}
66+
uses: ./.github/workflows/4.a-generate-webapi-clients.yaml
67+
permissions:
68+
contents: write
69+
packages: write
70+
with:
71+
# We cannot use environment variables here due to workflow limitation.
72+
# https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/reusing-workflows#limitations
73+
registry: ghcr.io
74+
image-repo: ${{ github.repository }}

‎.github/workflows/4.a-generate-webapi-clients.yaml

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: 4.a-Generate WebAPI client libraries
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
registry:
7+
type: string
8+
required: true
9+
image-repo:
10+
type: string
11+
required: true
12+
tag:
13+
type: string
14+
required: false
15+
default: latest
16+
workflow_dispatch:
17+
inputs:
18+
registry:
19+
type: string
20+
required: false
21+
default: ghcr.io
22+
image-repo:
23+
type: string
24+
required: false
25+
default: "green-software-foundation/carbon-aware-sdk"
26+
tag:
27+
type: string
28+
required: false
29+
default: latest
30+
31+
permissions:
32+
contents: write
33+
packages: write
34+
35+
jobs:
36+
detect-api-version:
37+
uses: ./.github/workflows/detect-webapi-version.yaml
38+
with:
39+
registry: ${{ inputs.registry }}
40+
image-repo: ${{ inputs.image-repo }}
41+
tag: ${{ inputs.tag }}
42+
43+
generate-java-client:
44+
needs: detect-api-version
45+
uses: ./.github/workflows/4.a.1-generate-webapi-client-java.yaml
46+
with:
47+
image: ${{ needs.detect-api-version.outputs.image }}
48+
apiver: ${{ needs.detect-api-version.outputs.apiver }}

‎.github/workflows/4.a.1-generate-webapi-client-java.yaml

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: 4.a.1-Generate WebAPI client library for Java
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
image:
7+
required: true
8+
type: string
9+
apiver:
10+
required: true
11+
type: string
12+
13+
jobs:
14+
generate-java-client:
15+
runs-on: ubuntu-latest
16+
services:
17+
webapi:
18+
image: ${{ inputs.image }}
19+
ports:
20+
- 8080:8080
21+
options: >-
22+
--health-cmd "curl -sS http://localhost:8080/health"
23+
--health-interval 3s
24+
--health-timeout 5s
25+
--health-retries 5
26+
permissions:
27+
packages: write
28+
env:
29+
API: http://localhost:8080/api/v1/swagger.yaml
30+
steps:
31+
- name: Prepare
32+
run: |
33+
mkdir work pages
34+
npm install -g @openapitools/[email protected]
35+
- name: Generate client library
36+
run: |
37+
echo '{"apiPackage": "foundation.greensoftware.carbonaware.webapi.client", "artifactDescription": "Carbon Aware SDK client library for Java", "artifactId": "casdk-client", "artifactVersion": "${{ inputs.apiver }}", "developerOrganization": "Green Software Foundation", "developerOrganizationUrl": "https://greensoftware.foundation/", "groupId": "foundation.greensoftware", "licenseName": "MIT License", "scmUrl": "${{ env.REPO }}", "artifactUrl": "${{ env.REPO }}/packages/", "scmConnection": "${{ github.repositoryUrl }}", "scmDeveloperConnection": "${{ github.repositoryUrl }}", "licenseUrl": "https://opensource.org/license/mit/", "developerName": "Green Software Foundation", "developerEmail": "[email protected]"}' > config.json
38+
openapi-generator-cli generate -i ${{ env.API }} -g java -o work -c config.json
39+
sed -i "s|</project>|<distributionManagement><repository><id>github</id><name>GitHub Packages</name><url>https://maven.pkg.github.com/${{ github.repository }}</url></repository></distributionManagement></project>|" work/pom.xml
40+
shell: bash
41+
- name: Setup Java 8
42+
uses: actions/setup-java@v4
43+
with:
44+
distribution: temurin
45+
java-version: 8
46+
cache: maven
47+
- name: Run Maven
48+
run: mvn -B deploy javadoc:javadoc
49+
env:
50+
GITHUB_TOKEN: ${{ github.token }}
51+
working-directory: work
52+
- name: Upload Javadoc
53+
uses: actions/upload-artifact@v4
54+
with:
55+
name: javadoc
56+
path: work/target/apidocs
57+
58+
push-javadoc:
59+
needs: generate-java-client
60+
concurrency: push-to-doc-website
61+
runs-on: ubuntu-latest
62+
env:
63+
DOCPATH: casdk-docs/static/client-apidocs/${{ inputs.apiver }}/java
64+
permissions:
65+
contents: write
66+
steps:
67+
- name: Checkout
68+
uses: actions/checkout@v4
69+
- name: Prepare
70+
run: mkdir -p ${{ env.DOCPATH }}
71+
- name: Download Javadoc
72+
uses: actions/download-artifact@v4
73+
with:
74+
name: javadoc
75+
path: ${{ env.DOCPATH }}
76+
- name: Push Javadoc
77+
run: |
78+
git config --global user.name "github-actions[bot]"
79+
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
80+
git add ${{ env.DOCPATH }}
81+
git commit -m "Add Javadoc for WebAPI ${{ inputs.apiver }}"
82+
git push origin ${{ github.ref_name }}
83+
env:
84+
GITHUB_TOKEN: ${{ github.token }}

‎.github/workflows/detect-webapi-version.yaml

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Detect API version from OpenAPI document in WebAPI container image
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
registry:
7+
type: string
8+
required: true
9+
image-repo:
10+
type: string
11+
required: true
12+
tag:
13+
type: string
14+
required: false
15+
default: latest
16+
outputs:
17+
image:
18+
value: ${{ jobs.make-image-name-for-pull.outputs.image }}
19+
apiver:
20+
value: ${{ jobs.detect-api-version.outputs.apiver }}
21+
22+
jobs:
23+
make-image-name-for-pull:
24+
runs-on: ubuntu-latest
25+
outputs:
26+
image: ${{ steps.make-image-name.outputs.IMAGE_NAME }}
27+
steps:
28+
- name: Make string for pulling container image
29+
id: make-image-name
30+
run: |
31+
REPO=${{ inputs.registry }}/${{ inputs.image-repo }}
32+
REPO_LOWER=${REPO,,}
33+
echo "IMAGE_NAME=$REPO_LOWER:${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
34+
35+
detect-api-version:
36+
needs: make-image-name-for-pull
37+
runs-on: ubuntu-latest
38+
services:
39+
webapi:
40+
image: ${{ needs.make-image-name-for-pull.outputs.image }}
41+
ports:
42+
- 8080:8080
43+
options: >-
44+
--health-cmd "curl -sS http://localhost:8080/health"
45+
--health-interval 3s
46+
--health-timeout 5s
47+
--health-retries 5
48+
outputs:
49+
apiver: ${{ steps.detect-api-version.outputs.CURRENT_API_VERSION }}
50+
steps:
51+
- name: Detect API version
52+
id: detect-api-version
53+
run: |
54+
API_VERSION=`curl -sS http://localhost:8080/api/v1/swagger.yaml | yq -r .info.version`
55+
echo "CURRENT_API_VERSION=$API_VERSION" >> "$GITHUB_OUTPUT"

‎samples/java-client/README.md

+12-41
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,19 @@
11
# Java Client Example
22

3-
This folder contains an example for WebAPI client in Java. Client library would
4-
be generated dynamically via
5-
[openapi-generator-maven-plugin](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin),
6-
and call WebAPI endpoints without HTTP code.
3+
This folder contains an example for WebAPI client in Java. Client library would be pulled from [GitHub Packages](https://github.com/orgs/Green-Software-Foundation/packages?repo_name=carbon-aware-sdk).
74

8-
Javadoc is [here](apidocs).
9-
10-
openapi-generator-maven-plugin generates Maven/Gradle project when it kicks,
11-
however this example uses generated codes directly. So you don't need to
12-
run/modify project files in it.
5+
Javadoc is [here](https://carbon-aware-sdk.greensoftware.foundation/client-apidocs/1.0.0/java).
136

147
## Requirements
158

16-
- OpenAPI spec file
17-
- Both online and offline file are available.
18-
- See [WebAPI document](../../docs/carbon-aware-webapi.md#autogenerate-webapi)
19-
for details.
209
- WebAPI instance
21-
- See the [Overview](../../docs/overview.md#publish-webapi-with-container)
22-
if you'd like to start it on container.
10+
- See the [Overview](../../docs/overview.md#publish-webapi-with-container) if you'd like to start it on container.
2311
- Java 8 or later
2412
- Maven
2513

2614
## Client code
2715

28-
[WebApiClient.java](src/main/java/foundation/greensoftware/carbonawaresdk/samples/java/WebApiClient.java)
29-
is an example program to call WebAPI endpoint. It calls all of endpoints, and
30-
shows the result.
16+
[WebApiClient.java](src/main/java/example/foundation/greensoftware/carbonawaresdk/WebApiClient.java) is an example program to call WebAPI endpoint. It calls all of endpoints, and shows the result.
3117

3218
Following methods are available:
3319

@@ -53,19 +39,14 @@ Following methods are available:
5339
- Call /emissions/average-carbon-intensity/batch
5440
- Shows average data for westus yesterday.
5541

56-
[OffsetDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html)
57-
is used for parameters in each APIs. However the error occurs if nano sec is set
58-
to it in case of WattTime. So it is highly recommended that clears nanosec field
59-
like `withNano(0)`.
42+
[OffsetDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html) is used for parameters in each APIs. However the error occurs if nano sec is set to it in case of WattTime. So it is highly recommended that clears nanosec field like `withNano(0)`.
6043

6144
## How it works
6245

6346
### 1. Set up for [POM](pom.xml)
6447

6548
You need to change following properties:
6649

67-
- `openapi.spec`
68-
- OpenAPI spec file
6950
- `webapi.endpoint`
7051
- WebAPI base URL
7152

@@ -83,27 +64,23 @@ $ mvn exec:java
8364

8465
### Running in container
8566

86-
This example also can run in container. You can use
87-
[Maven official image](https://hub.docker.com/_/maven).
67+
This example also can run in container. You can use [Maven official image](https://hub.docker.com/_/maven).
8868

89-
If you want to run both WebAPI and build process in container, you need to join
90-
2 containers to same network.
69+
If you want to run both WebAPI and build process in container, you need to join 2 containers to same network.
9170

9271
Following instructions are for Podman.
9372

9473
#### 1. Create pod
9574

96-
This pod publishes port 80 in the pod to 8080 on the host, then you can access
97-
WebAPI in the pod. The pod is named to `carbon-aware-sdk`.
75+
This pod publishes port 80 in the pod to 8080 on the host, then you can access WebAPI in the pod. The pod is named to `carbon-aware-sdk`.
9876

9977
```sh
10078
podman pod create -p 8080:80 --name carbon-aware-sdk
10179
```
10280

10381
#### 2. Start WebAPI container
10482

105-
Start WebAPI container in `carbon-aware-sdk` pod. It is specified at `--pod`
106-
option.
83+
Start WebAPI container in `carbon-aware-sdk` pod. It is specified at `--pod` option.
10784

10885
See [Overview](../../docs/overview.md) document to build container image.
10986

@@ -117,13 +94,9 @@ $ podman run -it --rm --pod carbon-aware-sdk \
11794

11895
#### 3. Run Maven in the container
11996

120-
Run `mvn` command in Maven container in `catbon-aware-sdk` pod. You need to
121-
mount Carbon Aware SDK source directory to the container. It mounts to `/src` in
122-
the container in following case.
97+
Run `mvn` command in Maven container in `catbon-aware-sdk` pod. You need to mount Carbon Aware SDK source directory to the container. It mounts to `/src` in the container in following case.
12398

124-
In following command, you can rebuild java-client, and can run the artifact. You
125-
can get artifacts from `samples/java-client/target` on the container host of
126-
course.
99+
In following command, you can rebuild java-client, and can run the artifact. You can get artifacts from `samples/java-client/target` on the container host of course.
127100

128101
```sh
129102
$ podman run -it --rm --pod carbon-aware-sdk \
@@ -132,6 +105,4 @@ $ podman run -it --rm --pod carbon-aware-sdk \
132105
mvn -f /src/samples/java-client/pom.xml clean package exec:java
133106
```
134107

135-
Maven will download many dependencies in each `mvn` call. You can avoid it when
136-
you mount `.m2` like `-v $HOME/.m2:/root/.m2` because it shares Maven cache
137-
between the host and the container.
108+
Maven will download many dependencies in each `mvn` call. You can avoid it when you mount `.m2` like `-v $HOME/.m2:/root/.m2` because it shares Maven cache between the host and the container.

0 commit comments

Comments
 (0)