This repo contains the information and the tools needed to automatically generate API clients for the Thy Street 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.

The process to genereate the clients explained in paragraphs below is fully automated through GitHub actions. The workflow will start every time code is pushed to master branch. 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:

• Arduino/PlatformIO
• Javascript
• Python

part from the 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 generated specs can be found at thystreet.yaml. 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.

The generator can validate the content of the spec, this should likely go in a CI step:

apigentools validate

To generate clients and documentation using a template, and apply pathces before template filling, this is the command to run:

apigentools generate

The 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-repo

apigentools 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 push

A 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 templates

There are other ways to provide upstream templates other than the currently configured, 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.