OpenAPI Generated Java Client for Equinix Metal

Prerequisite:

1. Jq (https://stedolan.github.io/jq/) : Jq command is used inside makefile to format OAS 3.0 json read from equinix public url.

    brew install jq
   

2. Docker : We can generate metal-java client in two ways (described in later section), first is via utilising swagger codegen image to consume metal OAS 3.0 spec which is provided as option in makefile. To install docker refer : https://docs.docker.com/engine/install/.

3. Building the API client library requires:

   1. Java 1.7+
   2. Maven

Running sample:

Build generated client:

cd equinix-openapi-metal
mvn clean package

The following executes list metro sample by consuming local jars produced after building generated metal-java client:

cd ..
java -classpath "equinix-openapi-metal/target/equinix-openapi-metal-1.0.0.jar:equinix-openapi-metal/target/lib/*" examples/ListMetros.java <API KEY TOKEN>

Generate and build equinix metal java client:

Using openapi generator v3 docker image :

make generate

Contribution guidelines

Patching oas3.0 spec

1. Make changes in spec/oas3.patched/ dir.
2. Create a patch file in metal-java:

   cd spec
   git diff oas3.patched/ > ../patches/spec.fetched.json/<patchfilename>
   cd ..
   

3. patchfilename should be in format: <patch_index>-<short_patch_decription_or_identifier>.patch
4. Run make patch to reapply the changes to oas spec.

Adding complex workflows

Complex workflows requiring multiple granular, autogenerated apis can be implemented as part of Operator classes. These classes are included in the path equinix-openapi-metal/src/main/java/com/equinix/workflow when building the sdk. An example use case for operator implementation can be for APIs requiring polling logic to fetch updated resource state.

1. Follow steps mentioned in section "Generate and build equinix metal java client" to generate and build the sdk in your cloned local.
2. Implement operator classes inside equinix-openapi-metal/src/main/java/com/equinix/workflow.
3. Follow steps mentioned in section "Functional tests for complex workflows" to add functional tests for the same.
4. After testing and debugging in your local, move the newly added operator classes to internal/workflow.
5. Commit your changes made in internal/workflow, .github/workflows, equinix-functional-tests and push them to the remote branch. The auto commit git workflow would automatically build and generate the sdk in the remote branch with the newly added workflows.
6. Post completion of the auto commit workflow in your remote branch, you can do a git rebase origin/your-branch-name to sync your local.

Adding functional tests for complex workflows

1. You can implement functional tests for your operator classes inside equinix-functional-test/src/test/java/com/equinix/test/functional. Check existing operator test implementations for reference.
2. Input properties required for the tests can be mentioned in a separate .properties file inside equinix-functional-test/src/test/resources.
3. To run functional tests locally:
   1. Pre-requisite: Steps 1 and 2 in section "Steps for development" have been followed.
   2. Open a terminal in equinix-openapi-metal and run mvn clean install --file pom.xml to install the sdk in your local.
   3. Add a run/debug configuration in your IDE. For example in IntelliJ, to run TestDeviceOperator functional tests locally in IntelliJ, add a maven configuration with :
      1. Configuration name set to equinix-run-device-functional-tests
      2. Working directory set to equinix-functional-test
      3. Run command set to clean test -Dtest=com.equinix.test.functional.TestDeviceOperator.java --file pom.xml
      4. If using environment variables, they can be added in Java options.
   4. Alternatively, you can do step iii through terminal directly.
4. For every new functional test, a separate github workflow .yaml should be defined inside .github/workflows. These can be run from Github's actions UI directly. Check existing workflow definitions for reference.

Release

This SDK is released via an on-demand GitHub Actions workflow.

When that workflow is run, it steps through the release process in roughly this order:

1. Determine the version number of the previous GitHub release
2. Identify Conventional Commit tags in the commit log since the previous release
3. Use the Conventional Commit tags to calculate the correct next version
4. Write the next version to the version file and regenerate the code
5. Commit the updated version and code
6. Create a GitHub release using the value in version for the tag & title
7. Rebuild SDK JARs and publish them to this repo's packages page