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 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.json
file.
Create theapp.js
file and doc
folder 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
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:
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.