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 a Python tool called apigentools that let us keep the spec files and the configuration bits in one single repo (this one) without duplicating the boilerplate on each git repo hosting the actual clients.
There is a blog post describing the system architecture.
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.
Following clients have been successfully generated with the present workflow:
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.
To be able to run the workflow locally in a developmnent environment, you'll need the following:
- Python 3.7+
- Apigentools 1.0+ (
pip install apigentools)
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.
The generator can validate the content of the spec, this should likely go in a CI step:
apigentools validateTo generate clients and documentation using a template, and apply pathces before template filling, this is the command to run:
apigentools generateThe previous command is fine for local development but in case the generated code has to be pushed upstream to each client's repository, run the previous command as follows:
apigentools generate --clone-repoapigentools has a simple command that can be invoked for each client generated
that will push the resulting code to different repos, using different branches
so the code can be reviewed and merged through a regular PR:
apigentools pushA release process should take from here and shouldn't be part of this workflow.
This step is not currently necessary as the generate step does it implicitly,
but in case you want to only apply patches to the original (upstream) templates
before the generation step, you can run it to check how the pathces will
modify the generated code. The step consists of cloning the openapi-generator
repo, applying one or more patches in the form of patch files to it and copy
the relevant templates in the folder templates:
apigentools templatesThere are other ways to provide upstream templates other than the currently configured
openapi-git that might be useful to speed up development iterations, please refer to
apigentools docs for more details.
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.