Swagger-jsdoc does not ref yaml file

Question

My swagger-jsdoc and swagger-ui-express setup to document my express app is apparently unable to read or reference YAML files that I am pointing them to

I am still learning how to document APIs, and I was using this article https://www.codementor.io/peteradeoye/splitting-your-swagger-spec-into-multiple-files-in-a-node-project-nuprc0mej as a guide but I am unable to replicate the desired results

This is my app.js

import 'core-js/stable';
import 'regenerator-runtime/runtime';
import express from 'express';
import bodyParser from 'body-parser';
import cors from 'cors';
import swaggerUI from 'swagger-ui-express';
import swaggerSpec from './config/swagger';
import allRoutes from './routes';


const app = express();

app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
app.use(cors());
app.use(bodyParser.urlencoded({
  extended: true,
}));
app.use(bodyParser.json());

allRoutes(app);

export default app;

This is my swagger config at ./config/swagger

const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  info: {
    title: 'REST API for Wayfarer', // Title of the documentation
    version: '1.0.0', // Version of the app
    description: 'This is the REST API for Wayfarer (a public bus transportation booking server.)', // short description of the app
  },
  host: 'localhost:3000', // the host or url of the app
  basePath: '/api/v1', // 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
export default swaggerJSDoc(options);

and this is one of the yaml I am referencing at ./docs/user.yaml

paths:
  /auth/signup:                # 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 the 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 definition for the request body
  signUp:
    type: object
        properties:
          username:
            type: string
          email:
            type: string
          password:
            type: string

I was expecting to see some info to be displayed when I try to view my documentation but what I see in my browser is No operations defined in the spec . I managed to narrow down the problem to

...
const options = {
  // import swaggerDefinitions
  swaggerDefinition,
  // path to the API docs
  apis: ['./docs/**/*.yaml'],
};
...

For some reason

...
apis: ['./docs/**/*.yaml'],
};
...

just refuses to work, I have renamed my docs folder too and that did not help. I moved my docs folder to the root of my project, the error message changed to Error: TypeError: Cannot convert undefined or null to object

Answer 1

I had the same issue. Try referencing the API document as an absolute path instead of a relative path. That worked for me. Also, make sure that all/any root-level properties are also defined within swaggerDefinition instead of within the .yaml file. If you're using OpenAPI 3.0 onwards, make sure to include this in swaggerDefinition as well, like so:

const swaggerDefinition = {
  openapi: '3.0.2',
  info: {
    title: 'REST API for Wayfarer', // Title of the documentation
    version: '1.0.0', // Version of the app
    description: 'This is the REST API for Wayfarer (a public bus transportation booking server.)', // short description of the app
  },
  host: 'localhost:3000', // the host or url of the app
  basePath: '/api/v1', // the basepath of your endpoint
};

Answer 2

The following is working for me: apis: [path.join(__dirname, '../docs/**/*.controller.js')]

Try using the path package and see if that resolves your issue.

Answer 3

the problem is that there is an error in your yaml file. You can check it out here: http://www.yamllint.com/

Also the path specified in apis: [] should be relative to your app.js, incase it isnt already.

Hope this helps !

Answer 4

The problem is on relative path in options. Use something like:

const options = {
  swaggerDefinition,
  apis: ['src/config/docs/**/*.yaml']
}

Answer 5

I had the same issue, and I finally solved it. You just need to use path.join() to refer to your YAML files.

in your case you need to change your code in this way:

 const path = require('path'); apis: [path.join(__dirname,'docs','**','*.yaml')]