Swagger centric APIs development in Node.js

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…

In this article, I want to share with you a technique that will highly reduce the overhead of APIs development and later integration testing in Node.js, using SwaggerExpress.js and OpenAPI Test Templates.

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.

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


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 documentationmockingimplementation 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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.