Does validation by `swagger-parser` actually work?

[Marc Hassan]

Describe the bug
The README says:

The resulting openapiSpecification will be a swagger tools-compatible (and validated) specification.

I may be misunderstanding what this means, but it doesn't seem like it is true. I am able to provide an invalid spec and swagger-jsdoc does not complain.

Looking at this code:

swagger-jsdoc/src/specification.js

Lines 100 to 104 in e1b8902

 parser.parse(swaggerObject, (err, api) => { 
   if (!err) { 
     specification = api; 
   } 
 }); 

The parse method from swagger-parser is asynchronous, but this library is not handling it that way.

To Reproduce

1. Create routes.js (note the invalid xxxdescriptionxxx property):

/**
 * @openapi
 * /:
 *   get:
 *     xxxdescriptionxxx: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

2. Create generate.js:

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: ['./routes.js'], // files containing annotations as above
};

const openapiSpecification = swaggerJsdoc(options);

console.log(JSON.stringify(openapiSpecification, null, 2));

3. Run generate.js and paste output in https://editor.swagger.io/
4. See that the spec is invalid

Expected behavior
swaggerJsdoc should error or warn when it encounters invalid spec