Splitting your swagger spec into multiple files in a Node project

Published Oct 06, 2018Last updated Apr 03, 2019

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 the app.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:

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

// Create global app objects
const app = express();

// Swagger definition
const swaggerDefinition = {
  info: {
    title: 'REST API for my App', // Title of the documentation
    version: '1.0.0', // Version of the app
    description: 'This is the REST API for my product', // short description of the app
  },
  host: 'localhost:3000', // the host or url of the app
  basePath: '/api', // the basepath of your endpoint
};

// options for the swagger docs
const options = {
  // import swaggerDefinitions
  swaggerDefinition,
  // path to the API docs
  apis: ['./docs/**/*.yaml'],
};
// initialize swagger-jsdoc
const swaggerSpec = swaggerJSDoc(options);

// use swagger-Ui-express for your app documentation endpoint
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

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:

paths:
  /users/:                # path of the user from your endpoint
    post:                 # endpoint request type (post request)
      tags:               # Tag property
        - User            # Value of the tag
      summary: creates a new user
      produces:
      - application/json
      parameters:         # request parameters
      - in: body          # request body
        name: sign up     # name of request, can be any name
        description: It enables a user to create an account
        required: false   # can also be true depending on user preference
        schema:           # Schema definition
          $ref: '#/definitions/signUp' 
      responses:          # server responses
        201:
          description: An object with user details
definitions:        # Schema defination for request body
  signUp:
    type: object
    properties:
      user:
        type: object
        properties:
          username:
            type: string
          email:
            type: string
          password:
            type: string

** 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

paths:
  /pet/{id}:         # path of the user from your endpoint
    put:              # endpoint request type (put request)
      tags:
        - Pet
      summary: It updates a pet profile detail
      produces:
      - application/json
      parameters:     # request parameters
      - name: id      # name of parameter passed
        in: path      # parameters in the path
        description: path parameter takes the pet id
        required: true
        type: string
      - in: body
        name: update pet
        description: It enables a user to update pet profile
        required: false
        schema:
          $ref: '#/definitions/updatePet'
      responses:
        200:
          description: An object with a user updated user profile detail
        401:
          description: Unauthorized users
definitions:        # Schema definition for the request body
  updatePet:
    type: object
    properties:
      pet:
        type: object
        properties:
          petname:
            type: string
          petFavorite:
            type: string
          image:
            type: string
          password:
            type: string

Save the two files and type