Design APIs first in Node.js using Swagger, without swagger templating

Think APIs first, design micro-services better

PS: This is without tightly using swagger templates & swagger tools, using a simple way and uses swagger-ui-express

If you know what is Design API first and you want to know how to avoid swagger templating, yet publish swagger APIs, then go to section “Publish and review your APIs with stake holders” at the bottom

APIs enable interoperability, which is a key ask in modern cloud ecosystems.

Why is it important to think API first

  • Shifts our thinking, we think about design of backend as a participating service in the ecosystem, instead of monolith
  • Encourages Design by Contract and helps parallel development cycles
  • Effective to understand, communicate, review with your stake holders
  • Directs towards, thinking about experience of user
  • Testable APIs from the beginning

How to do it

Designing the API first and quickly trying it out with your stake holders is the best way to do it, below is a one such suggested method, I welcome addition, correction and your comments

Though we will discuss with example in Node.js, this is easily applicable to other tech stacks

1. Design APIs

  • Semantically define URI signature (HTTP Method, Path, Path variables)
  • Identify query parameters, request body structure
  • Identify expected Response (success, business exceptions, errors)

2. Test APIs with Mock data

  • Generate test cases for APIs
  • Try out APIs with Mock or sample data
  • Identify different possible sample data

3. Review with stake holder by publishing API Document

  • Publish documented APIs to stake holders, along with mock data or sample data
  • Give your stake holder a playground to try out APIs
  • From here, you can iterate Step #1 through 3, if you have not yet got them correct

4. Implement APIs

  • Use MVC architecture and implement the APIs
  • Continuously test APIs using the same test cases generated during step #2
  • Deploy them for your stake holders to try, use and provide feedback
  • From here, you can iterate Step #1 through 4, if you have not yet got them correct

How Swagger helps

Swagger is a open source tool for API Lifecycle, enabling us to do the above described New version Swagger v3.0 aims to standardise the lifecycle by calling it OpenAPI, however I am referring to Swagger v2.x

PS: I am not sure, if there is a specific API Lifecycle as such, above described can be considered as a lifecycle

Swagger helps

  • Document API design as a specification and save in a YAML or JSON format, in swagger.yaml or swagger.json
  • Interactively document the APIs specification (edit swagger.yaml/json)
  • Generate Mock data for the APIs from the specification file swagger.yaml or swagger.json
  • Generate test cases using supertest
  • Generate a beautiful HTML UI for documentation of APIs and try out API from the UI

Setting up & install Swagger

All these steps are same on an existing nodejs project, not just a new project

Swagger is installable using npm or yarn, install it globally, as it will be used across projects

npm install -g swagger swagger-editor

Swagger can generate boilerplate for your project ( swagger project create), I decided not to use it, as it was suiting my regular best practices for organizing the project's code structure

Why I did not used the swagger generated template ? Best practice is to keep your code as self contained modules and vertically sliced, which is agile way, this was not what I got from generated scaffolding of swagger

Create API design spec

Once you have installed swagger, you can start using it to create/edit your API documentation, swagger looks for API documentation spec file at folder <project root>/api/swagger/, you can keep your API document spec as swagger.yaml or as swagger.json, I chose to keep it as YAML (no specific reason, just lazy to enclose strings in double quotes in JSON :-) )

touch <project root>/api/swagger/swagger.yaml

If you decide ever to use JSON, you can convert YAML to JSON easily, below should help you

Edit API design spec interactively

You can now edit the API design spec interactively and design the API

swagger project edit
API design spec in interactive edit mode using swagger

If you need a seed design spec to begin with, you can use below

I am using v2.0, soon we can start using v3.0 once it stabilizes (at the time of writing release candidate is out but still fixes pending)

for demo purpose, have added few API specs in my demo code base here

Generate test cases

Once you have designed your APIs, you can generate supertest powered API BDD test cases using below

# if folder does not exist, create it so that swagger does not throw the error 
mkdir -p ./test/api/client

and then
swagger project generate-test

The generated test, is in BDD style, hence it will be using the URL to initilise the supertest request object, I have modified it to use the express middleware instead, so that i don’t have to run the app separately to run the test case and I could automate running my test cases

i.e., example of exporting your express app as a middleware so that it can be used in another module, such as supertest test cases

in app.js

const app = require('express')(); 
app.use('/', function (req, res) { res.send('hello'); });
// Note, we are exporting our express middleware instead of starting listen directly 
// this does not make much difference but simplifies your app startup sequence, enables testing automation
module.exports = app 

in a bin/www or index.

const app = require('../app'); 

This is used to modify the generated test cases of swagger (usually around line number #54), which otherwise will be pointing to http://localhost:3000

var api = supertest(require('../../../app')); // supertest init;

Now you are all set to run your test cases using mocha or swagger, execute these commands from project root folder

mochamocha test/api/client/*test.js
swagger swagger project test

The generated test cases from swagger will not have data populated, in case you wish to automate that too, read this by Subeesh Chothen

Publish and review your APIs with stake holders

You can are ready to view & publish the API document as a HTML UI

However a small step is needed to do this, since we are not using swagger generated project template

To do this we will use a npm module as middleware swagger-ui-express, which with simple steps can host your swagger UI documentation as a middleware

To integrate this module, add it to your dependency and put below code snippet in your express middleware

npm install --save swagger-ui-express

and then

Once the above is done, you can start the app and view the documentation at mounted path

Please refer complete working code here to learn more about this

npm start


swagger project start

View, Review, Try Out APIs using a nice UI

From the UI you can even try out the API, if implementation is ready and running

Thats all for now, later will try update this post on Mock data

Leave your comments, suggestion, questions, critique, they are most valuables for me

Keep calm, keep coding…!