Skip to content

BINDGEN.md

Latest commit

 

History

History
42 lines (27 loc) · 4.14 KB

BINDGEN.md

File metadata and controls

42 lines (27 loc) · 4.14 KB

Autogenerated Go bindings for the Onshape API

This repository makes use of Github workflows and a custom fork of the Go OpenAPI generator in order to automatically build and deploy Onshape bindings. The build system is configurable through the bindgen-config.json file. The automated system is currently configured to run each day, and may also be triggered manually from the Actions tab on GitHub. The system makes use of the reusable GitHub workflows in the Onshape OpenAPI utilities repository. For each reusable workflow in the utilities repository, there is a "stub" workflow in this repository that is used to invoke it. There are three GitHub workflows included in the system:

  • Update Bindings: This action downloads the latest version of the Onshape API specification with the fetch settings in bindgen-config.json. It will automatically push a commit to main if the specification has changed.
  • Generate Bindings: This action removes old generator files from the onshape directory, applies a preprocessing pass specified in bindgen-config.json, and then invokes the custom OpenAPI generator. If the generator causes new changes, the changes are placed in a branch and a pull request is created. The pull request will then be merged automatically if there are no conflicts and all tests pass.
  • Test Bindings: This action runs go test ./... on the generated bindings, ensuring all tests pass. This action will run as a check on all new pull requests.

Update Bindings will run automatically at 12:00 AM UTC each day. If it commits changes to openapi.json, then Generate Bindings will be invoked automatically, causing a new pull request and merge to occur.

Generation settings

The generator may be configured to run at a regular interval. This may be changed by modifying the Update Bindings workflow at .github/workflows/update-bindings.yml.

Update Bindings

The Update Bindings workflow may be customized by changing the fetch node in bindgen-config.json. The following fields affect specification fetching:

  • url: The base URL with which to query the API.
  • versionAlias: The version type. Either null, "LAST_MINOR", or "LAST_BUILD".
  • userRole: The REST user role. Either "PUBLIC" or "INTERNAL".
  • operationIds: The set of endpoints to include. Either null or a list of strings.

Generate Bindings

Binding generation may be customized by changing the generate tag in bindgen-config.json. The following fields affect binding generation:

  • generatorUrl: The URL from which to fetch the OpenAPI generator JAR.
  • customGeneratorUrl: The URL from which to fetch the OpenAPI generator JAR.
  • preprocess: The preprocess key accepts a list of preprocessor directives, each of which are a JSON object that includes the key to modify and the type of update (either update or remove). update preprocessor directives also include a value tag, with the new value that should replace the current one. Once all keys have been successfully modified, the output of the preprocessor is passed to the OpenAPI generator.

Building bindings locally

In some cases, it may be preferable to generate a copy of the bindings without relying on GitHub actions or the remote. In this case, two bash scripts are included that can be used to generate the bindings on a local machine. To do so, the following prerequisites are required:

  • A copy of openapi.json from Glassworks containing the bindings to generate
  • Java 8
  • The json NPM package
  • A copy of the OpenAPI generator JAR, placed in the repository directory and named openapi-generator-cli.jar
  • A copy of the custom Go generator, placed in the repository directory and named go-oapi-codegen.jar

To build the bindings, first run /.github/workflows/preprocess.sh to generate a valid OpenAPI specification according to the rules specified in the config file. Then, run /.github/workflows/bindgen.sh to create a copy of the bindings. The repo environment variable may be used to set the repository path for both scripts, and the packageVersion environment variable can be employed to set the Go package version for the bindgen.sh script.