iot-api clients generator

This repo contains the informations and the tools needed to automatically generate API clients for the iot-api service in any language supported by OpenAPI generator.

The OpenAPI generator is orchestrated by git workflow using openapi-generator official images.

[IMPORTANT] Client generation process

The process to generate the clients explained in paragraphs below is fully automated through GitHub actions. The workflow will start every time a tag in the form of vX.Y (e.g. v2.1) is pushed to this repo. If the workflow completes successfully, a PR will be opened for each client in their respective git repositories. See the actions page to monitor the status of a workflow.

Sample clients

Following clients have been successfully generated with the present workflow:

• Go
• Python
• Javascript

Generation process

After initial setup (the procedures needed to setup this git repo), the ideal workflow consists in updating this repo every time the API service changes, re-generate all the clients, push the generated code to the git repo it belongs to and release the updated clients (this last step may vary depending on the programming language).

The operations are detailed in the following paragraphs.

Get an updated version of the API specification

In this case the specs are generated by Goa using Swagger and they can be found at http://api2.arduino.cc/iot/swagger.json. To be more future proof and to leverage the latest versions of the tools available, we're using the version 3 of the OpenAPI for the generator, this means that the output from Goa must be converted into a compatible spec like the one in this repo.

Several conversion tools from OpenAPI v2 to v3 exist, and some of them can be easily integrated in a CI, so major updates will be performed by either:

• have Goa produce a v3 OpenAPI spec
• dump the Goa spec, convert to v3 and update this repo

Minor updates might be done manually since v3 uses Yaml and the resulting spec is human friendly.

Generate the clients

Update openapi definition in openapi/components folder. 'Release' github workflow will take care of:

• update and merge openapi specifications
• update templates with provided patches
• generate clients
• create PRs with updated code in destination clients repositories

Customization

The code generator can be fine tuned using templates. By patching existing templates for each language or adding new ones, any aspect of the resulting client can be adjusted to fit custom needs: the readme, the docs, the tests, the model classes themselves can be changed downstream, and changes will reflect on the resulting client.