Splitting your swagger spec into multiple files in a Node project

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 DesktopYou can then create a folder named swagger-doc on your desktop using the command below
mkdir swagger-docNavigate to the directory using
cd swagger-docIn the swagger-doc directory, run
npm initFollow 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 docTo 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-expressAfter 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
In the docs folder, we will create two YAML file
user.yaml
pet.yamlTo document a user POST request body to
localhost:3000/api/userswith 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:
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.json your terminal to run your server. Open your browser and go to
localhost:3000/docsto 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.
