Add GHA workflow for generating WebAPI client library for Java

[YaSuenag]

Pull Request

This is successor of #359

Summary

Add GHA workflow to generate WebAPI client library for Java. This workflow would be triggered when API version in swagger.yaml is updated in each release. Client library would be published into GitHub Packages. See my package repo as an example: https://github.com/YaSuenag/carbon-aware-sdk/packages/2078122

This PR introduced 3 workflow files:

• detect-webapi-version.yaml
  • Detect API version in swagger.yaml in latest container in GitHub Packages
• generate-webapi-clients.yaml
  • Gateway workflow for generating WebAPI client libraries
  • This workflow can be called from both 4-release.yaml and workflow dispatch
  • This workflow would not be triggered by 4-release.yaml if API version is not updated in the release
• generate-webapi-client-java.yaml
  • Generates WebAPI client for Java

API document (Javadoc) would be added client-apidocs in gh-pages branch directly. See my repo as an example: https://github.com/YaSuenag/carbon-aware-sdk/tree/gh-pages/client-apidocs

If you want to add another WebAPI clients (JS, Python, .NET, and so on), you need to add new workflow for generating, and add its entry point to generate-webapi-clients.yaml.

Changes

This PR contains 3 siginificant commits. I left them due to ease of review, but you can squash them when you merge.

• YaSuenag@421f14e
  • Adds new workflow
• YaSuenag@b9b261c
  • Clarify OpenAPI document version and title
  • Please update version number if you bump up API version in future
• YaSuenag@0f4f83d
  • Update Java client example
  • This is big change because Javadoc has been removed

Checklist

• Local Tests Passing?
• CICD and Pipeline Tests Passing?
• Added any new Tests?
• Documentation Updates Made?
• Are there any API Changes? If yes, please describe below.
• This is not a breaking change. If it is, please describe it below.

Are there API Changes?

Clarify API version in swagger.yaml. Current version is 1.0 (maybe it is default by .NET), new version is 1.0.0.

Is this a breaking change?

API version in swagger.yaml (1.0 - 1.0.0)

Anything else?

config.json for OpenAPI generator:

{
  "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]"
}

[YaSuenag]

@danuw I want to hear your opinion especially following topics:

• Naming convention of workflow files
  • Better to name 4.a-generate-webapi-clients.yaml 4.a.1-generate-webapi-client-java.yaml?
  • detect-webapi-version.yaml is ok? It is reusable workflow - it does not have any triggers excepts workflow call.
• Push client API docs to gh-pages branch directly?
  • Is this operation ok?
  • Is the location of API documents ok? ( client-apidocs/<version>/<language> )

[YaSuenag]

⚠️Some files (e.g. .github/workflows/detect-webapi-version.yaml) maps port 80 in WebAPI container to 8080 of localhost. All of them should be updated after #404 . .NET 8 exposes 8080 by default.

[danuw]

As per @YaSuenag 's comments we are waiting on a dependency from .net 8 migration changes.
Blocked merge for now

[YaSuenag]

This PR is blocked by #489 - we need to fix port number of WebAPI container after #489.

[YaSuenag]

I updated this PR. This refer to .NET 8 migrated WebAPI container, then it works fine on my forked repo. Please review!

[YaSuenag]

I updated this PR to upload client API doc for Java (aka Javadoc) to casdk-docs/static/client-apidocs/${{ inputs.apiver }}/java on dev branch directly. Javadoc will be committed / pushed to dev branch directly by the workflow when OpenAPI version is updated. Can we accept this behavior? @danuw

[YaSuenag]

@danuw @vaughanknight
I've merged current dev into this PR. It works fine on my forked repo - I can publish WebAPI client library for Java to GitHub Packages.

So can you review this?

Note that this workflow would create a commit for API document (Javadoc) to default branch (dev in this case).
Example of the commit: YaSuenag@81adc17

[danuw]

LGTM

Let's generate those client libraries and monitor if any issues

[danuw]

Should this be added to project assembly variables in the future? so version is not maintained as hardcoded value in the code?

[danuw]

Let's apply the related changes (if any, in the NPM PR that should follow)