How To Convert An OpenAPI Specification Into A NodeJS SDK

The OpenAPI Specification [↗] provides developers and technical writers with a way to document APIs. Unlike traditional text-based documentation, the formal nature of the spec allows detailed descriptions of the API to be captured such as the data type of parameters, the exact structure of responses, etc

This allows for some interesting things such as being able to generate code based on the specification. This is exactly what Readme.io [↗] provides with their SDK generator [↗].

This NodeJS [↗] package takes in the JSON version of your API spec and produces NodeJS wrapper code you can immediately use to interact with your APIs.

They mention supporting other programming languages in the future at the moment only NodeJS is supported.

Setting up

For this tutorial, I have gone ahead and created an OpenAPI spec [↗] based on the Reqres [↗] API mock server.

To get started create a directory to house your code. Next, we will go ahead and install the node package "api" using npx [↗].


$ npx api install  https://gist.githubusercontent.com/EDDYMENS/f7aa590591e618c690601bead7ef9287/raw/838aa7f7559bd23ff663e321e3b480446ef4210c/reqres.openapi.json

If you don't have npx, you can install it by running npm install -g npx within your terminal.

During the installation process, you will be asked a few questions.

For the SDK name I used test you might want to do the same so you can run the code examples I share later in the tutorial.

For the language I chose Javascript.

At the end of the installation process a hidden folder .api will be created. This is code generated based on the OpenAPI spec we provided.

We can now go ahead and test out a few functions. To get started create an index.js file for the code we will be writing.

We will be using NodeJs to execute the code that follows, thus: $ node index.js.

Making a GET request

First, let's look at making a GET request. To be honest it's no different from all the other requests.

The main thing you need to know is that operationId within the spec is what is used as the method names, in this case, thus getUsers. Also, the request body and query parameters are passed to the method as parameters.

Also note how we require @api/test where test is the name we chose for our SDK during the setup process.


01: const testSDK = require('@api/test');
02: 
03: testSDK.getUsers(1).then(({ data }) => {
04:     console.log(' getUsers output:', data);
05:   });

Making a POST request

The request body is passed to the method as a parameter just like the query parameter above. You might get a parameter hint letting you know the expected parameter structure depending on the editor you are using.


01: const testSDK = require('@api/test');
02: 
03: testSDK.addUser(
04:   {
05:     name: "James",
06:     job: "Carpenter"
07:   }
08: ).then(({ data }) => {
09:   console.log('addUser output:', data);
10: });

Making an Update request

In the case of the update/put method, we need to pass two parameters the request body containing the data to update to and the Id of the record we will like to update. We pass both in as parameters to the updateUser method.


01: const testSDK = require('@api/test');
02: 
03: testSDK.updateUser(
04:   {
05:     name: "James",
06:     job: "Plumber"
07:   },
08:   {id: 1}
09: ).then(({ data }) => {
10:   console.log('updateUser output:', data);
11: });

Making a DELETE request


01: const testSDK = require('@api/test');
02: 
03: testSDK.deleteUser(2).then(({ data }) => {
04:    console.log('deleteUser output:', data);
05:  });

Conclusion

There are many more methods and different ways to work with the package. To learn more check out the official documentation [↗].

Here is another article you might like 😊 Mark an open API spec endpoint as deprecated

Tech Jobs | Newsletter [↗] 🗯️ Got a question? 🔗 Share on 𝕏

EDDYMENS