Procedures to develop Node-RED node from OpenAPI document
In this post, I will explain how to use the “Node generator” which makes it easy to create Node-RED nodes.
What is the Node generator?
Node generator is a command-line tool that can create custom nodes automatically. This tool provides functionality to generate the code of Node-RED node from Open API document like Swagger Codegen. In addition to the Open API document, it also supports JavaScript code in a function node as a source file. Using this tool, Node developers can easily develop and publish their custom nodes on the flow library to share them with other Node-RED users.
After Hitachi research & development group released this tool as open-source software, it has been managed as the sub-project of the Node-RED project under the OpenJS Foundation (Linux Foundation). Currently, the Node-RED development community has enhanced the functionality of this tool in a cooperative way.
As of now, not only Hitachi but also Node-RED user companies like Cisco and IBM have used this tool to develop their original nodes as you can see on the following websites.
- Use case in Cisco: https://developer.cisco.com/meraki/meraki-dashboard-api-node-red-node/
- Use case in IBM US: https://developer.ibm.com/tutorials/use-node-red-node-generator-to-create-new-nodes-from-apis-and-services/
What is the OpenAPI document?
OpenAPI document is a standard format to describe the specification of the REST API.
The OpenAPI document contains information about the description of the REST API, HTTP methods about how to access the REST API in YAML or JSON format as above example.
Generating Node-RED node from OpenAPI document
From now on, I will try to generate the Node-RED node from the OpenAPI document. In the following procedures, I will use the OpenAPI document of the REST API which retrieves the location information of the International Space Station (ISS).
In this document, the operating system is Windows which has Node.js and Node-RED. The Node generator supports not only Windows but Linux and macOS. Therefore, you can run the tool on various OS environments if you change the file path.
(1) Install Node generator
After opening the command prompt as Administrator mode, install Node generator (node-red-nodegen module) and the build tool (windows-build-tools module) in the case of Windows.
— — — — — — — — — — — — — — — — — — — — —
npm install -g node-red-nodegen
npm install -g windows-build-tools (Windows only)
— — — — — — — — — — — — — — — — — — — — —
(2) Close the command prompt
(3) Download the OpenAPI document
Download the OpenAPI document from https://raw.githubusercontent.com/kazuhitoyokoi/nodegen-handson/master/swagger.yaml , and then save the file to the home directory (For example, C:\Users\< User name >).
(4) Move to the home directory
Reopen the command prompt as the user mode, and then, move to the home directory using the change directory command.
— — —
cd
— — —
(5) Generate node module from the OpenAPI document
Generate node from the OpenAPI document using the Node generator command (node-red-nodegen). The first argument of the command should be the OpenAPI document file saved in the home directory.
— — — — — — — — — — — — — —
node-red-nodegen swagger.yaml
— — — — — — — — — — — — — —
After executing the command, I can get the generated node module successfully. A new directory, node-red-contrib-iss-location under the home directory will emerge. Inside this directory, there are files and directories that the node module consists of.
For the next step, I will use the generated node module from Node-RED.
(6) Move to the generated directory
— — — — — — — — — — — — —
cd node-red-contrib-iss-location
— — — — — — — — — — — — —
(7) Install dependency modules and prepare to create a symbolic link
— — — —
npm link
— — — —
(8) Move to the Node-RED home directory
— — — — — —
cd
cd .node-red
— — — — — —
(9) Create a symbolic link
— — — — — — — — — — — — — — — —
npm link node-red-contrib-iss-location
— — — — — — — — — — — — — — — —
(10) Launch Node-RED
Using the node-red command, I will start Node-RED. If the Node-RED process already runs in the computer, stop the process using Ctrl+c keys and restart Node-RED.
— — — —
node-red
— — — —
After I run it successfully, there will be a new green iss-location node on the palette of the Node-RED flow editor ( http://<IP address>:<Port number> ).
To configure the node property, I will drag and drop the iss-location node to the central workspace. After opening the node property, I can see the pulldown menu to select the endpoint which was defined in the OpenAPI document.
To check the behaviors of the node, I will place the inject node before the iss-location node and the debug node after the iss-location node. And then, I will wire them in the processing order and click the deploy button. After clicking the button of the inject node, the debug tab outputs latitude and longitude of the current ISS location.
As the next step, I will install the world map node, node-red-contrib-web-worldmap to show the world map using OpenStreetMap. To install the node to Node-RED, select “Manage palette” on the menu of the Node-RED flow editor, and then, select “Palette” and “Install” on the user settings. On the node installation UI, input “node-red-contrib-web-worldmap” to search it and click “install” button.
Create the flow to visualize the current ISS location
To create processing flow, place the change node and worldmap node which has the left port additonaly. And wire these nodes to create an entire flow.
Each setting in the node property is as follows.
(1) Setting in inject node property
- Repeat: interval, every 1 second
(2) Setting in iss-location node property
- Method: ISS-Location-Now
(3) Setting in change node property
The message specification from the iss-location node and the message specification to the worldmap node have different formats. Therefore, I need to convert the message specification using the following settings in the change node.
- Set msg.payload.lat to msg.payload.iss_position.latitude
- Set msg.payload.lon to msg.payload.iss_position.longitude
- Set msg.payload.name to payload.timestamp
(4) Setting in the worldmap node property
In the worldmap node, there are no settings that I need to change in the node property.
After configuring the node property settings above (1 to 4), click the deploy button on the upper right corner of the Node-RED flow editor.
Checking the flow behavior
To show the world map, access the URL, http://<Node-RED IP address>:<port number>/worldmap. If the flow runs successfully, I would be able to see pins that refer to the ISS location on the world map. I can click the plus and minus buttons on the top left corner of the world map to change the map scale.
If there is no pin on the world map, I need to check the node property settings in each node. For example, I need to check the JSON path in the change node property or select the method in the iss-location node property, etc.
Summary
Using the Node generator tool, node developers can develop their original Node-RED nodes without additional coding if their REST API services have the OpenAPI document.
The details of how to use the Node generator and tips on how to develop the node modules are available in this wiki page:
