build(openapi): phase 2 - generate kotlin clients

[jagpreetsinghsasan]

Meta

A major refactoring of this issue has been done by Peter on 2022-05-03

I've broken this up into two phases, this is the issue for the second phase.

• The first phase (build(openapi): phase 1 - generate kotlin clients #2000) is to do what's being described here only for the Corda v4 connector (./packages/cactus-plugin-ledger-connector-corda/src/main/json/openapi.json)
• The second phase is to do it for all the rest of the openapi.json spec files, but that comes only once phase one has been reviewed and tested (with the post-merge git tag baed release automation included)

Description

As a developer I want to not be forced to use the NodeJS/Javascript API client if my primary programming language is something else so that I can achieve high productivity through Cactus no matter the language I'm using.

This is different from a similar looking issue which discusses the possibility of writing plugins in different languages as well.

Here is a complete list of programming languages that are supported by the OpenAPI generator (which we can take full advantage of since we are using the OpenAPI specs)
https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources

How to get going with this?

1. First you can establish that the code generation works at all by running it locally.
   Take a look at "generate-sdk": named scripts in the package.json files.
   You can get a list of the openapi.json files that need to be covered by searching for them with a handy tool called find

   $ find ./ -iwholename "./**/src/main/json/openapi.json"
   ./examples/cactus-example-supply-chain-business-logic-plugin/src/main/json/openapi.json
   ./examples/cactus-example-carbon-accounting-business-logic-plugin/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-google-sm/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-quorum/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-fabric/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-iroha/src/main/json/openapi.json
   ./packages/cactus-plugin-htlc-eth-besu/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-besu/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-azure-kv/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-memory-wasm/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-xdai/src/main/json/openapi.json
   ./packages/cactus-core-api/src/main/json/openapi.json
   ./packages/cactus-plugin-htlc-eth-besu-erc20/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-aws-sm/src/main/json/openapi.json
   ./packages/cactus-plugin-odap-hermes/src/main/json/openapi.json
   ./packages/cactus-plugin-ledger-connector-corda/src/main/json/openapi.json
   ./packages/cactus-cmd-api-server/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-memory/src/main/json/openapi.json
   ./packages/cactus-plugin-keychain-vault/src/main/json/openapi.json
   ./packages/cactus-plugin-consortium-manual/src/main/json/openapi.json
   ./extensions/cactus-plugin-object-store-ipfs/src/main/json/openapi.json
   ./extensions/cactus-plugin-htlc-coordinator-besu/src/main/json/openapi.json

2. Once verified that the code generation can work, add scripts similar to the existing ones that generate the typescript code ("generate-sdk": ) and call those scripts the same in each package, like "generate-client-java".

3. Identify a set of suitable candidates for publishing the JVM artifacts, then have a conversation with Peter about which one should we pick.

4. Then add the workflow yaml file for publishing on git tags made on the main branch.

Acceptance Criteria

1. Clients for Java are generated as part of the full build (the CI/CD pipeline)
2. Dev builds only build the Typescript API client to remain as fast as possible
3. Publishing of the Java API clients is included in the release process => if a tag is added on the main branch, the Java client is published/made available for public consumption the same way we do with the Typescript API client (it gets published to npm for Java this would be some other repository)
   3.1 Identify candidates of where to publish Java artifacts - ask the Hyperledger Foundation community architects on Discord about what other projects have done/do.
4. The generated source code must be under the correct directory in each package. For example for the Corda v4 connector you would place it under here: packages/cactus-plugin-ledger-connector-corda/src/main/kotlin/generated/openapi/kotlin-client/ (https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/kotlin-client)
5. There must be openapi-kotlin-client-publish.yaml github workflow file that does the publishing which gets triggered on git tags on the main branch (e.g. when we issue a release)

4. Client side routing is supported by the Java API clients as well.

cc: @takeutak @sfuji822 @jonathan-m-hamilton

Update 2022-05-03: Crossed out acceptance criteria 4 until a more detailed design of it can be provided.

[jagpreetsinghsasan]

Currently there is very limited support for oneOf, allOf, anyOf support for OpenApi v3.x
This feature is yet to be implemented for Java and other languages as per the roadmap and the issues
Roadmap: https://openapi-generator.tech/docs/roadmap/#short-term
Java Issue: OpenAPITools/openapi-generator#5381

[petermetz]

OpenAPITools/openapi-generator#5381 Has been resolved in the meantime so this can be restarted. I made updates accordingly.

[jagpreetsinghsasan]

There are still some issues while using OneOf to generate kotlin client.
Tested on openapi-generator version 5.2.0, 5.2.1, 5.4.0 (Haven't tried it with 6.x versions as that makes the ts code unfunctional as well)

If one tries to generate kotlin code with the attached openapi.json file at the end of this comment (you can paste it in any package openapi.json) and then add this to their package.json

"generate-sdk:kotlin": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g kotlin -o ./src/main/kotlin/generated/openapi/kotlin-client/ --reserved-words-mappings protected=protected",

Then run in the package,

yarn generate-sdk:kotlin

Then navigate to
src/main/kotlin/generated/openapi/kotlin-client/src/main/kotlin/org/openapitools/client/models/Alpha.kt
One can check the last line starting with val currentDate: OneOfLess
This is creating issues for plugins like xdai, quorum etc where OneOf is used extensively

I tried creating another object in the schemas which has the entire oneOf: [ ... , ... , ... ] array and then referred it to the places where OneOf is mentioned.

But that creates another set of problem with Kotlin code generation (The problem is, it generates empty classes of this referenced oneOf object)

[openapi file]

{
    "openapi": "3.0.3",
    "info": {
        "title": "Hyperledger Cactus Plugin - Connector Quorum",
        "description": "Can perform basic tasks on a Quorum ledger",
        "version": "0.0.1",
        "license": {
            "name": "Apache 2.0",
            "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "components":{
        "schemas": {
            "Alpha": {
                "type": "object",
                "required": [],
                "properties": {
                    "CurrentDate":{
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "number"
                            }
                        ]
                    }
                }
            }
        }
    },
    "paths": {
        "/api/getDate": {
            "get": {
                "x-hyperledger-cactus": {
                  "http": {
                    "verbLowerCase": "get",
                    "path": "/api/getDate"
                  }
                },
                "operationId": "getDate",
                "summary": "Get the Date",
                "parameters": [],
                "responses": {
                  "200": {
                    "description": "OK",
                    "content": {
                      "text/plain": {
                        "schema": {
                          "$ref": "#/components/schemas/Alpha"
                        }
                      }
                    }
                  }
                }
              }
        }
    }
}