https://github.com/arduino/clients-iot-api
Automated pipeline to generate clients and docs for Arduino IoT API
https://github.com/arduino/clients-iot-api
api arduino golang iot javascript openapi python rest swagger
Last synced: 5 months ago
JSON representation
Automated pipeline to generate clients and docs for Arduino IoT API
- Host: GitHub
- URL: https://github.com/arduino/clients-iot-api
- Owner: arduino
- Created: 2019-08-20T10:30:45.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-06T09:55:24.000Z (over 1 year ago)
- Last Synced: 2025-01-29T10:51:29.542Z (about 1 year ago)
- Topics: api, arduino, golang, iot, javascript, openapi, python, rest, swagger
- Language: Go
- Homepage: https://www.arduino.cc/en/IoT/HomePage
- Size: 822 KB
- Stars: 3
- Watchers: 9
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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][0] 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](https://github.com/bcmi-labs/clients-iot-api/actions) to
monitor the status of a workflow.
## Sample clients
Following clients have been successfully generated with the present workflow:
* [Go](https://github.com/arduino/iot-client-go)
* [Python](https://github.com/arduino/iot-client-py)
* [Javascript](https://github.com/arduino/iot-client-js)
## 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][2]. 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][3].
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][4]. 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.
[0]: https://openapi-generator.tech/docs/generators
[1]: https://github.com/DataDog/apigentools
[2]: http://api2.arduino.cc/iot/swagger.json
[3]: clients-iot-api/spec/v2/swagger.yaml
[4]: https://openapi-generator.tech/docs/templating