Add 2b-generate-java-client.yaml

[YaSuenag]

Pull Request

#252

Summary

Add GitHub workflow to generate Java client library of WebAPI.

2b-generate-java-client.yaml would be kicked by 2-pre-release.yaml to generate Java client library of WebAPI. It would be generated via OpenAPI generator, and OpenAPI document comes from WebAPI container made by 2-pre-release.yaml .

Artifact of 2b-generate-java-client.yaml would be published to GitHub Packages as a Maven library, so we can write dependency into pom.xml in your project. Artifact version (version number which is identified in file name) comes from OpenAPI document version - it is different from CASDK version. If the document comes from pre-release container, it would be handled as SNAPSHOT which means upstream dev version.

https://github.com/YaSuenag/carbon-aware-sdk/packages/1814194

This workflow also generates Javadoc (API document of Java library), so it should be published into doc-website branch.

This PR would pass following configuration to OpenAPI generator:

{
  "apiPackage": "foudation.greensoftware.carbonaware.webapi.client",
  "artifactDescription": "Carbon Aware SDK client library for Java",
  "artifactId": "casdk-client",
  "artifactVersion": "${{ steps.detect-api-version.outputs.API_VERSION }}",
  "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": null
}

Changes

• .github/workflows/2-pre-release.yaml
• .github/workflows/2b-generate-java-client.yaml

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?

No

Is this a breaking change?

No

[YaSuenag]

As I wrote in description, this PR contains code to publish Javadoc (API document) to doc-website branch. Now I set it to docs/apidocs/<version>/java, , but I'm not sure it is correct. It will be clarified with OSS WG (see #344 (comment) CC: @Willmish @danuw )

I keep this PR as draft until the location of API document is clarified.

[codecov-commenter]

Codecov Report

Merging #359 (907b999) into dev (b3b3189) will not change coverage.
The diff coverage is n/a.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

@@           Coverage Diff           @@
##              dev     #359   +/-   ##
=======================================
  Coverage   74.21%   74.21%           
=======================================
  Files          77       77           
  Lines        2637     2637           
  Branches      266      266           
=======================================
  Hits         1957     1957           
  Misses        598      598           
  Partials       82       82           

[danuw]

Hi @YaSuenag, are you able to update that PR now?

Let me know if you need me.

[YaSuenag]

@danuw
As I wrote before, I'd like to deploy client API document (Javadoc: static content) to GitHub Pages, so I'm waiting for conclusionof #344.

[YaSuenag]

@danuw I could deploy Java API document (Javadoc) to casdk-docs/static/client-apidocs/<API version>/java in your docs/docusaurus-setup branch as you mentioned in #344 . So I'm ready to integrate upload code to the workflow, however #344 have to be integrated before this PR of course.

Thus I'm waiting for #344.

[YaSuenag]

I'm considering release timing of client libraries. I think it might be better to trigger this workflow (generate client libraries) manually.

OpenAPI document is different from CASDK release. The document wouldn't be updated if API spec is not changed. For example, if CASDK v2.0 provides WebAPI which compliant to API v1.0 (same with CASDK v1.1) ongoingly, we don't need to update OpenAPI document.

OpenAPI document has .info.version field to specify the document version, but it does not mean API version as the reference said. In general, API version would be specified in the URI (e.g. http://localhost/api/v1/). So I think it is better to flow in below:

1. Update WebAPI version of CASDK
2. Update workflow for client libraries (to refer new API version)
3. Create GA of CASDK in GitHub Release page
4. Dispatch parent workflow to controll to generate client libraries in manually
   • call automatically -> Java
   • call automatically -> JS
   • call automatically -> .NET
   • ...

What do you think?

[danuw]

I agree though we were going to have pre release too tight cause supposedly you want to test this is all still working as expected whether tests are automated or manual right?

We should connect to discuss how we want to test these things so we can progress this quickly.

[YaSuenag]

I agree though we were going to have pre release too tight cause supposedly you want to test this is all still working as expected whether tests are automated or manual right?

API version does not synchronize with the SDK release as I said before. It means new client libraries might be released even if the new SDK is not released. So I don't know yet what is the best trigger to release client libraries. I think to kick the workflow is the best when the SDK maintainer acknowledge to update the API version.

[YaSuenag]

I continue this work in #471