Splitting your swagger spec into multiple files in a Node project

Splitting swagger spec best tool for team collaboration

After lots of research online on how to write documentation using swagger on the local environment instead of using swagger online editor for easy team collaboration, I discovered that no good articles could point me through the right direction. I spent days searching for articles online but couldn’t lay my hand on any that suit my purpose. I had to do lots of research before I could finally come up with what I want.

First thing first, you need to create a directory for the project, navigate to your desktop by typing the following command in your terminal

cd Desktop

You can then create a folder named swagger-doc on your desktop using the command below

mkdir swagger-doc

Navigate to the directory using

cd swagger-doc

In the swagger-doc directory, run

npm init

Follow the instruction to set up the package.jsonfile.

Create theapp.js file and docfolder in the root directory of your project using

touch app.js 
mkdir doc

To use this tutorial, you need to install the following npm package:
1. swagger-jsdoc
2. swagger-ui-express

To install this packages, you need to run

npm install --save swagger-jsdoc swagger-ui-express

After successful installation, open theapp.js file and import the following file at the top of the file.

const express = require('express');
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

Below your imported file write the following lines of code

Swagger Configuration

In the docs folder, we will create two YAML file

user.yaml
pet.yaml

To document a user POST request body to

localhost:3000/api/users

with a request body similar to the one below:

{
   user: {
      'username': 'Peter',
      'email': 'peter@gmail.com',
      'password': 'password'
   }
}

In the user.yaml file, type in the code below:

Note: The indentation is very important, swagger will return an error if you didn’t indent properly

To document a PUT request body for

localhost:3000/api/pet/{petid}

with a request body similar to the one below.

{
   pet: {
      'petname': 'Peter',
      'petFavorite': 'beans',
      'image': 'image.gif',
      'password': 'password'
   }
}

open the file pet.yaml and type in the code below

Save the two files and type

node app.js

on your terminal to run your server. Open your browser and go to

localhost:3000/docs

to view your swagger documentation.

You should get something similar to the screenshot below

You can check the full code on Github.

Thanks for taking out time to read this article.

Do you need to hire top developers? Talk to Andela to help you scale.
Are you looking to accelerate your career as a developer? Andela is currently hiring senior developers. Apply now.