Docs/improve validator docs (#228)

* ci: remove npm unnecesary files

* docs: update validator example

* docs: improve validator readme docs

* chore: bump version to 1.7.1

* chore: remove vscode editor options

* chore: bump version to 1.8.0

* fix: sonarcloud example code errors

* fix: major sonarcloud issues

* fix: minor sonarcloud issues

Author: kevinccbsg

.gitignore

@@ -4,7 +4,7 @@
 
 ### Linux ###
 *~
-
+.vscode
 # temporary files which can be created if a process still has a handle open of a deleted file
 .fuse_hidden*
 

.npmignore

@@ -2,3 +2,4 @@
 npm-debug.log
 examples
 test
+.github

.vscode/launch.json

@@ -37,6 +37,7 @@ npm i express-jsdoc-swagger
 ## Basic Usage
 
 ```javascript
+// index.js file
 const express = require('express');
 const expressJSDocSwagger = require('express-jsdoc-swagger');
 
@@ -54,6 +55,7 @@ const options = {
       scheme: 'basic',
     },
   },
+  // Base directory which we use to locate your JSDOC files
   baseDir: __dirname,
   // Glob pattern to find your jsdoc files (multiple patterns can be added in an array)
   filesPattern: './**/*.js',
@@ -94,7 +96,7 @@ app.listen(PORT, () => console.log(`Example app listening at http://localhost:${
 
 ## Basic Examples
 
-1. Basic configuration
+1. Basic configuration options.
 
 ```javascript
 const options = {
@@ -129,7 +131,7 @@ const options = {
  */
 ```
 
-3. Endpoint that returns a `Songs` model array
+3. Endpoint which returns a `Songs` model array in the response.
 
 ```javascript
 /**
@@ -145,6 +147,24 @@ app.get('/api/v1/albums', (req, res) => (
 ));
 ```
 
+3. Endpoint PUT with body and path params which returns a `Songs` model array in the response.
+
+```javascript
+/**
+ * PUT /api/v1/albums/{id}
+ * @summary Update album
+ * @tags album
+ * @param {string} name.path - name param description
+ * @param {Song} request.body.required - songs info
+ * @return {array<Song>} 200 - success response - application/json
+ */
+app.put('/api/v1/albums/:id', (req, res) => (
+  res.json([{
+    title: 'abum 1',
+  }])
+));
+```
+
 4. Basic endpoint definition with tags, params and basic authentication
 
 ```javascript
@@ -203,23 +223,34 @@ Install using the node package registry:
 npm install --save express-oas-validator
 ```
 
-After this you have to initialize using the `finish` event. More info in this [sections](eventEmitter.md).
+We have to wait until we have the full swagger schema to initiate the validator.
 
 ```js
-const instance = expressJSDocSwagger(app)(options);
+// validator.js
+const { init } = require('express-oas-validator');
 
-instance.on('finish', data => {
-  init(data);
-  resolve(app);
+const validators = instance => new Promise((resolve, reject) => {
+  instance.on('finish', (swaggerDef) => {
+    const { validateRequest, validateResponse } = init(swaggerDef);
+    resolve({ validateRequest, validateResponse });
+  });
+
+  instance.on('error', (error) => {
+    reject(error);
+  });
 });
+
+module.exports = validators;
+
 ```
 
-This is a full example of how it works.
+You can check out this also in our [example folder](https://github.com/BRIKEV/express-jsdoc-swagger/tree/master/examples/validator).
 
 ```js
+// index.js
 const express = require('express');
 const expressJSDocSwagger = require('express-jsdoc-swagger');
-const { init, validateRequest, validateResponse } = require('express-oas-validator');
+const validator = require('./validator');
 
 const options = {
   info: {
@@ -236,15 +267,10 @@ const options = {
 const app = express();
 const instance = expressJSDocSwagger(app)(options);
 
-const serverApp = () => new Promise(resolve => {
-  instance.on('finish', data => {
-    init(data);
-    resolve(app);
-  });
-
+const serverApp = async () => {
+  const { validateRequest, validateResponse } = await validator(instance);
   app.use(express.urlencoded({ extended: true }));
   app.use(express.json());
-
   /**
    * A song
    * @typedef {object} Song
@@ -292,9 +318,21 @@ const serverApp = () => new Promise(resolve => {
   app.use((err, req, res, next) => {
     res.status(err.status).json(err);
   });
-});
 
-module.exports = serverApp;
+  return app;
+};
+
+const PORT = process.env.PORT || 4000;
+
+serverApp()
+  .then(app => 
+    app.listen(PORT, () =>
+      console.log(`Listening PORT: ${PORT}`)
+    ))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
 ```
 
 You can visit our [documentation](https://brikev.github.io/express-jsdoc-swagger-docs/#/validator).

README.md

@@ -2,7 +2,7 @@ const doctrine = require('doctrine');
 
 const jsdocInfo = (options = { unwrap: true }) => comments => {
   if (!comments || !Array.isArray(comments)) return [];
-  const parsed = comments.map(comment => {
+  return comments.map(comment => {
     const parsedValue = doctrine.parse(comment, options);
     const tags = parsedValue.tags.map(tag => ({
       ...tag,
@@ -15,7 +15,6 @@ const jsdocInfo = (options = { unwrap: true }) => comments => {
       description,
     };
   });
-  return parsed;
 };
 
 module.exports = jsdocInfo;

consumers/jsdocInfo.js

@@ -43,7 +43,7 @@ expressJSDocSwagger(app)(options);
  * @param {number} id.path - song id
  * @return {oneOf|IntrumentalSong|PopSong} 200 - success response - application/json
  */
-app.get('/api/v1/song/:id', (req, res) => (
+app.get('/api/v1/song/:id', (_req, res) => (
   res.json({
     title: 'abum 1',
   })

examples/combineSchemas/index.js

@@ -57,6 +57,6 @@ expressJSDocSwagger(app)(options);
  * @summary This is the summary of the endpoint
  * @return {string} 200 - success response
  */
-app.get('/api/v1', (req, res) => res.send('Hello World!'));
+app.get('/api/v1', (_req, res) => res.send('Hello World!'));
 
 app.listen(port, () => logger.info(`Example app listening at http://localhost:${port}`));

examples/configuration/main.js

@@ -57,6 +57,6 @@ expressJSDocSwagger(app)(options);
  * @summary This is the summary of the endpoint
  * @return {string} 200 - success response
  */
-app.get('/api/v1', (req, res) => res.send('Hello World!'));
+app.get('/api/v1', (_req, res) => res.send('Hello World!'));
 
 app.listen(port, () => logger.info(`Example app listening at http://localhost:${port}`));

examples/configuration/multipleFiles.js

@@ -51,6 +51,6 @@ expressJSDocSwagger(app)(options);
  * @summary This is the summary of the endpoint
  * @return {array<Song>} 200 - success response - application/json
  */
-app.get('/api/v1/albums', (req, res) => res.json([]));
+app.get('/api/v1/albums', (_req, res) => res.json([]));
 
 app.listen(port, () => logger.info(`Example app listening at http://localhost:${port}`));

examples/configuration/swaggerOptions.js

@@ -35,7 +35,7 @@ expressJSDocSwagger(app)(options, userSwagger);
  * @param {array<object>} name.query.required - name param description
  * @return {array<object>} 200 - success response - application/json
  */
-app.get('/api/v1/albums', (req, res) => (
+app.get('/api/v1/albums', (_req, res) => (
   res.json([{
     title: 'abum 1',
   }])

examples/merge/simple.js

@@ -37,14 +37,14 @@ expressJSDocSwagger(app)(options);
  * @param {Song} request.body.required - Song to add
  * @return {string} 200 - Success message
  */
- app.post('/api/v1/songs', (req, res) => res.send('You saved a song!'));
+ app.post('/api/v1/songs', (_req, res) => res.send('You saved a song!'));
 
 /**
  * GET /api/v1/song
  * @summary Nullable props in response
  * @return {array<Song>} 200 - List of songs
  */
-app.get('/api/v1/song', (req, res) => res.json([
+app.get('/api/v1/song', (_req, res) => res.json([
   {
     id: 1,
     title: 'Song from album',

examples/nullableFields/explicitNullable.js

@@ -36,6 +36,6 @@ expressJSDocSwagger(app)(options);
  * @param {Song} request.body.required - Song to add
  * @return {string} 200 - Success message
  */
-app.post('/api/v1/songs', (req, res) => res.send('You saved a song!'));
+app.post('/api/v1/songs', (_req, res) => res.send('You saved a song!'));
 
 app.listen(port, () => logger.info(`Example app listening at http://localhost:${port}`));