Run command swagger-jsdoc shows "You must provide sources for reading API files."

Question

Run command swagger-jsdoc shows "You must provide sources for reading API files."

keke78ui9 opened this issue 3 years ago · 8 comments

Describe the bug
When I run swagger-jsdoc command show the error message "You must provide sources for reading API files." and didn't create swagger.json file.

To Reproduce

install the latest swagger-jsdoc (version 6.1.0)
create swaggerConfig.js file to contain swagger API definitions.
run command swagger-jsdoc -d swaggerConfig.js
shows the error "You must provide sources for reading API files" and didn't create swagger.json file.

Expected behavior
Should create swagger.json file.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

OS: MacOS
Browser: not browser
Version [6.1.0]

Additional context
If I run command swagger-jsdoc -d swaggerConfig.js anyArg with any additional arguments, then works.
Also, compare the version, looks like swagger-jsdoc@5.0.1 works, but version 6.0.0 doesn't work.

Answer 1 · 2022-01-07T12:26:39.000Z

Hi, @keke78ui9 can you share the swagger config file that you have been using?

Answer 2 · 2022-01-07T17:23:06.000Z

Hi @daniloab,

This is from the /examples/app/swaggerDefinition.cjs, but by do the following step you can see the same message as well.

const host = `http://${process.env.IP}:${process.env.PORT}`;

module.exports = {
  info: {
    // API informations (required)
    title: 'Hello World', // Title (required)
    version: '1.0.0', // Version (required)
    description: 'A sample API', // Description (optional)
  },
  host, // Host (optional)
  basePath: '/', // Base path (optional)
};

use master branch latest
npm intall
cd ./example/app
node ../../bin/swagger-jsdoc.js -d swaggerDefinition.cjs
Should see the "You must provide sources for reading API files."
and if you do node ../../bin/swagger-jsdoc.js -d swaggerDefinition.cjs arg
it return message "Swagger specification is ready."

I checked the code little bit at bin/swagger-jsdoc.js, looks like this program.args is empty array at following line, not sure what will be the correct expectation.

if (!program.args.length) {
  console.log('You must provide sources for reading API files.');
  process.exit();
}

Answer 3 · 2022-02-08T13:13:56.000Z

Hi @keke78ui9 did you filled the api array with api's path(s) ?

  const options = {
    swaggerDefinition: {
      info: {
        title: 'API', // Title (required)
        version: '2.0.0', // Version (required)
      },
    },
    apis: [
      './src/module/swagger/swagger.yaml',
      './src/routes/*.js', // Path to the API docs from root
      './src/module/swagger/parameters.yaml'
    ],
  };

Answer 4 · 2022-03-11T20:45:03.000Z

I am experiencing the same issue as @keke78ui9

Here is my swaggerDef.js file:

const DOMAIN = process.env.SERVER_DOMAIN;
const PORT = process.env.SERVER_PORT;
const VERSION = require('../package.json').version;
const TITLE = require('../package.json').description;

const host = http://${DOMAIN}:${PORT};

module.exports = {
info: {
// API informations (required)
title: TITLE, // Title (required)
version: VERSION, // Version (required)
description: How to use ${TITLE} // Description (optional)
},
apis: ['./app/route/ * * /index.ts', './app/dashboard/socket/index.ts'], // <-- We add this property
host: host, // Host (optional)
basePath: '/' // Base path (optional)
};

It works fine on version 4 and 5.

This is the error on 6

$ ./node_modules/.bin/swagger-jsdoc -d dist/swaggerDef.js -o dist/api-docs.json

You must provide sources for reading API files.

What am I doing wrong?

I also tried this example:

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

const options = {
definition: {
openapi: '3.0.0',
info: {
// API informations (required)
title: TITLE, // Title (required)
version: VERSION, // Version (required)
description: How to use ${TITLE} // Description (optional)
},
},
apis: ['./app/route/ * * /index.ts', './app/dashboard/socket/index.ts'], // <-- We add this property
host: host, // Host (optional)
basePath: '/' // Base path (optional)
};

const openapiSpecification = swaggerJsdoc(options);

This is the error I received:

$ ./node_modules/.bin/swagger-jsdoc -d dist/swaggerDef.js -o dist/api-docs.json

Definition file should contain an info object!
More at http://swagger.io/specification/#infoObject

Answer 5 · 2022-03-11T20:56:12.000Z

I reverted to 5.0.1 to fix problem.

Answer 6 · 2022-03-29T00:06:19.000Z

Same issue, version 6 broke it, reverting to 5.0.1 makes it work

Answer 7 · 2022-04-18T14:09:29.000Z

Hi @daniloab,

This is from the /examples/app/swaggerDefinition.cjs, but by do the following step you can see the same message as well.
const host = `http://${process.env.IP}:${process.env.PORT}`;

module.exports = {
  info: {
    // API informations (required)
    title: 'Hello World', // Title (required)
    version: '1.0.0', // Version (required)
    description: 'A sample API', // Description (optional)
  },
  host, // Host (optional)
  basePath: '/', // Base path (optional)
};
use master branch latest

npm intall

cd ./example/app

node ../../bin/swagger-jsdoc.js -d swaggerDefinition.cjs

Should see the "You must provide sources for reading API files."

and if you do node ../../bin/swagger-jsdoc.js -d swaggerDefinition.cjs arg

it return message "Swagger specification is ready."

I checked the code little bit at bin/swagger-jsdoc.js, looks like this program.args is empty array at following line, not sure what will be the correct expectation.
if (!program.args.length) {
  console.log('You must provide sources for reading API files.');
  process.exit();
}

If you do not provide your APIs the swagger-jsdoc will return this error

You must provide sources for reading API files.

As you can see in the own tests from swagger-jsdoc repo here:

to make work provide the API source for swagger-jsdoc works normally.

I will close this issue because it work when passing the API sources. If you want to change this behavior to make work only with swagger definition open a new issue with it and feel free to send a pull request making this work.

Answer 8 · 2023-02-07T19:57:04.000Z

Hi @daniloab,

error is still present.

Node: v16.18.1
npm: 8.19.2
swagger-jsdoc: 6.2.5

Here is my definition file.

const config = require('../config');
const { SWAGGER_CONFIG } = config;
const { securityDefinitions, security, schemes, host } = SWAGGER_CONFIG;

module.exports = {
    info: {
        title: 'Headnote Payments API',
        version: '1.0.1',
        description: 'Headnote Payments API',
    },
    apis: [
        __dirname + '/../v1/firms/**/*.js',
        __dirname + '/../v1/transactions/**/*.js',
        __dirname + '/../v1/../../legacy_api_transformers/*.js'
    ],
    securityDefinitions,
    security, // Security for all endpoints. Can be overridden within individual path items and/or methods.
    schemes, // A list of protocols
    host, // Host
    basePath: '/v1', // Base path,
}

I use swagger-jsdoc --definition ./src/api/swagger/swaggerDef.js -o src/api/swagger/swagger_schema.json to generate a schema file. I have got You must provide sources for reading API files.