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 · 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.

Danilo Assis · Answer 1 · Fri Jan 07 2022 20:26:39 GMT+0800 (China Standard Time)

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

keke78ui9 · Answer 2 · Sat Jan 08 2022 01:23:06 GMT+0800 (China Standard Time)

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();
}

matt-dkt · Answer 3 · Tue Feb 08 2022 21:13:56 GMT+0800 (China Standard Time)

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'
    ],
  };

Brian Pilati · Answer 4 · Sat Mar 12 2022 04:45:03 GMT+0800 (China Standard Time)

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

Brian Pilati · Answer 5 · Sat Mar 12 2022 04:56:12 GMT+0800 (China Standard Time)

I reverted to 5.0.1 to fix problem.

Roberto Arosemena Elizondo · Answer 6 · Tue Mar 29 2022 08:06:19 GMT+0800 (China Standard Time)

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

Danilo Assis · Answer 7 · Mon Apr 18 2022 22:09:29 GMT+0800 (China Standard Time)

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.

dkarpov-w · Answer 8 · Wed Feb 08 2023 03:57:04 GMT+0800 (China Standard Time)

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.