OpenAPI 3 meets NodeJS
Ignacio Peluaga, Pablo Fernandez , Pedro J. Molina, Rafael Fresno
At the ISA Group, one of our main interest is the research on APIs development. We care about following standards, and we are a proud member of the OpenAPI Initiative (in case you are not familiar, please take a look at this post) . As such, we would love to use the latest version of the OpenAPI Specification, v3.0.x. Sadly, we could not find any tool for Node.js that allowed us to easily create OAS 3.0.x applications, as most current tools only support the old Swagger 2.0 specification. That is why we decided to create our own tools to help us and any other interested developers who are in the same situation.
Therefore, we want to present a couple of tools we have recently developed: oas-tools and oas-generator. The former is highly inspired by the well-known swagger-tools, and any application using this tool can be easily upgraded by following some simple steps (more on this later). The latter is a command line utility that can be used to quickly generate a Node.js server, given an input 3.0 specification file, just like Swagger Editor (with the use of swagger-codegen) does with 2.0 files in its editor. This generated server will be ready to work by just installing the needed dependencies and including your additional logic in the appropriate controllers.
Oas-tools
oas-tools can be used to replace swagger-tools by following a series of steps. First, you need to install both oas-tools and express, as servers generated by Swagger will use connect by default. Then, you need to perform some small changes in the code: change your server from connect to express, replace references to swagger-tools with oas-tools, and include the server object as a parameter of the initializeMiddleware function. Then, upgrade your Swagger 2.0 specification file to OAS 3.0 by using any tool that can perform this task, like Mermade openapi-converter, and check that no errors were made in the conversion by validating the resulting file (swagger editor is handy tool for that). Finally, due to some changes in version 3.0 of the specification, you need to add an x-name property to each requestBody in the specification file. We have a short video showing all these steps:
More info: https://github.com/isa-group/oas-tools
Oas-generator
Using the second tool, oas-generator, is also easy. Just create a 3.0 specification file (following the previous mentioned steps), install the utility using npm, and execute a simple command:
oas-generator path/to/spec/file.yaml -n serverNameUPDATE! oas-generator version 2.0 includes swagger-ui documentation and test portal out of the box; you can access relative URL /docs to see it in action.
You will have a server generated within seconds. If you would rather like to have a zip file containing the server, you can do it by just adding the -z flag to the command. Again, we have prepared a video in which we use this tool:
More info: https://github.com/isa-group/oas-generator
Final remarks
We are looking forward for your contributions as issues or pull request. We also provide the links to the utilities in npm, in case you want to check them out:
- oas-tools: https://www.npmjs.com/package/oas-tools
- oas-generator: https://www.npmjs.com/package/oas-generator
and of course…Happy coding!
About ISA-Group
We are the Applied Software Engineering (ISA) research group at the University of Seville, in the south of Spain. Our group is composed of professors, researchers, and enthusiastic students working on the automated management of service level agreements, but we also extend our research to many other areas. You can find more information about us in our website.
