Swagger centric APIs development in Node.js

Rolando Santamaria Maso
Mar 16 · 4 min read

During the last week I came across an interesting success case in my software development experiences: “self -generated contracts validation and API tests using Swagger specs…

I agree, writing enough tests to guarantee high “lines and cases coverage” levels require a lot of effort and will usually drain developers energy and motivation…

Keep effective! — photo courtesy of https://pexels.com

Your API implementation should start with your Swagger Spec

But, what is Swagger?

Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.
https://en.wikipedia.org/wiki/Swagger_(software)

Swagger is also known as OpenAPI.

Building our Swagger Spec

Using the existing open-source tools to build Swagger Specs is rather simple. Let’s take the following example as our project use case:

Minimalist Pets Swagger Spec example: https://editor.swagger.io/?url=https://raw.githubusercontent.com/jkyberneees/swagger-api-tests/master/PetStore.yaml

You can read the complete Swagger Specification v2 here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

I have my Swagger based API spec, now what?

In this article we are gonna be using the awesome swagger-express-middleware, among other features you have:

  • Supports Swagger 2.0 specs in JSON or YAML
  • Thoroughly tested
  • Mock middleware
  • Metadata middleware
  • Parse Request middleware
  • Validate Request middleware
  • CORS middleware
  • Files middleware

You can explore more details here: https://www.npmjs.com/package/swagger-express-middleware#features

Mock your API

Once you have defined you API, there is no need to block frontend teams from starting their development, just right away you can expose your HTTP service, mocking all endpoints according to the Swagger Spec:

HTTP API with all endpoints mocked according to Swagger Spec 💪

Implement your endpoints

Now is time to implement your endpoints with real business work-flows. For the purpose of simplicity, in this example we only have to implement the GET /pets endpoint and respect the response schema:

Expected response schema for GET /pets endpoint
Implementing the GET /pets endpoint

Generate and execute API tests using the Swagger Spec as your contract reference 🚀

Now is the time to create “magic”, let’s generate and execute integration tests using the API contracts defined in the Swagger Spec. To do this we are gonna use the oatts module, and yes, it is very simple:

oatts test scripts examples
npm test script execution results

Conclusions

First things first:

Swagger is great!

In the enterprise world, we usually require to start documenting API contracts before any implementation starts. Here, Swagger is the number 1 tool for that.
Therefore we might not be surprise why the Node.js frameworks also ship-in plugins for integrating our APIs with it:

In this article we have described a quick trip from documentation, mocking, implementation and testing.

Of course, for the purpose of simplicity we have used a minimalist API with just one endpoint; but I can guarantee you that the oatts will generate all possible tests according to your Swagger Specs.
It also allows you to attach custom values for complex tests workflows… https://github.com/google/oatts#custom-values
Also remember, oatts ensures the responses from your API endpoints match the expected contract.

Finally, you can find a fully working demo at: https://github.com/jkyberneees/swagger-api-tests

sharenowTech

SHARE NOW TECH Blog

Rolando Santamaria Maso

Written by

ENTHUSIASTIC AND PASSIONATE COMPUTER SCIENCES ENGINEER. CURRENTLY A NODE.JS CHAPTER LEAD AT SHARE-NOW…

sharenowTech

SHARE NOW TECH Blog