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
You can then create a folder named
swagger-doc on your desktop using the command below
Navigate to the directory using
swagger-doc directory, run
Follow the instruction to set up the
app.js file and
docfolder in the root directory of your project using
To install this packages, you need to run
npm install --save swagger-jsdoc swagger-ui-express
After successful installation, open the
app.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
To document a user POST request body to
with a request body similar to the one below:
user.yaml file, type in the code below:
To document a PUT request body for
with a request body similar to the one below.
open the file
pet.yaml and type in the code below
Save the two files and type
on your terminal to run your server. Open your browser and go to
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.