Automatic API Client Generation
This page will illustrate how to generate API clients in various different programming languages, using the updated OpenAPI schema for OpenRemote.
The process begins by understanding the tools about to be used. Specifically, The OpenAPI Specification provides a formal standard for describing HTTP APIs. With a bit more brevity, we can say that an OpenAPI file describes an HTTP API. The routes, inputs, and outputs, its authorization and authentication procedures, etc.
While it is an incredible tool for open-source projects and an invaluable resource for new team members, it can also be used for automating a wide array of processes that may be required within a platform. Specifically, using open-source applications, it also allows for the creation of dummy API servers, dummy data, and various "dry run" simulation data that could be useful for assuring product quality in an automated fashion.
Another tool that the OpenAPI specification enables us to use is API client generators. In essence, if there is a text file containing the definition of a server, then the file can be used to create a program that can communicate with the server, given that all required variables (for example API credentials) are provided.
This type of tool is what we will employ for our OpenRemote API client. Specifically, we will use OpenAPI Generator, a fork of Swagger Codegen, which is developed by Smartbear, its former owner.
Follow the guide in the Manager APIs page, and press on the .json link under the API's title, or simply head to http://<baseUrl>/api/master/openapi.json. You can also use the demo instances of OpenRemote and use the OpenAPI.json file from there.
The tutorial, to be ran 100% offline, requires to install the latest version of any distribution of OpenAPI-Generator. This includes these installation methods:
- npm
- homebrew
- Scoop
- a Docker image
- a JAR file
- a bash script
To generate a client, use the command <however you invoke openapi-generator> generate -i <OpenAPI file> -g <generator to use> -o <output directory>.
If the command was valid, the generator will have produced some files within <output directory>. The terminal will also show you the result of the operation.
You can find the list of generators here.
Applying the packages in a project could be intimidating, since there is not a big amount of documentation for all of the different generators.
As a general guideline, if you are not publishing the generated client, you may sometimes get away by dropping the generated library folder in the libraries folder for your language (node_modules for npm, site_packages for Python, etc.).
If you are publishing the generated API client, you should then import it into your project by installing it directly for your framework's package manager.