Refactor error messages (#69)

* feat: improve error messages with a placeholder

* docs: update readme and package description

* docs: update package.json

README.md

@@ -7,7 +7,7 @@
 
 # express-jsdoc-swagger
 
-With this library, you can document your endpoints using swagger [OpenAPI 3 Specification](https://swagger.io/specification/) without writing YAML or JSON. You just have to write comments on your endpoints and swagger UI will be automatically generated.
+With this library, you can document your express endpoints using swagger [OpenAPI 3 Specification](https://swagger.io/specification/) without writing YAML or JSON. You can write jsdoc comments on each endpoint, and the library is going to create the swagger UI.
 
 ## Prerequisites
 This library assumes you are using:
@@ -21,7 +21,6 @@ npm i express-jsdoc-swagger
 
 ## Usage
 ```javascript
-
 const express = require('express');
 const expressJSDocSwagger = require('express-jsdoc-swagger');
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "express-jsdoc-swagger",
   "version": "1.0.2",
-  "description": "Swagger generator based in jsdoc",
+  "description": "Swagger OpenAPI 3.x generator",
   "main": "index.js",
   "dependencies": {
     "chalk": "^4.0.0",
@@ -41,9 +41,10 @@
   },
   "keywords": [
     "swagger",
+    "swagger-generator",
+    "express",
     "jsdoc",
     "node",
-    "express",
     "docs",
     "documentation",
     "swagger-ui",
@@ -54,5 +55,5 @@
   "bugs": {
     "url": "https://github.com/BRIKEV/express-jsdoc-swagger/issues"
   },
-  "homepage": "https://github.com/BRIKEV/express-jsdoc-swagger#readme"
+  "homepage": "https://brikev.github.io/express-jsdoc-swagger-docs/#/"
 }

test/e2e/errors/errors.test.js

@@ -19,11 +19,11 @@ test('should give a nice error message for responses', async () => {
   expect(console.warn).toHaveBeenCalledTimes(2);
   expect(console.warn).toHaveBeenNthCalledWith(
     1,
-    chalk.yellow('Entity: @return could not be parsed. Value: "200 - success response - application/json" is wrong'),
+    chalk.yellow('[express-jsdoc-swagger] Entity: @return could not be parsed. Value: "200 - success response - application/json" is wrong'),
   );
   expect(console.warn).toHaveBeenNthCalledWith(
     2,
-    chalk.yellow('Entity: @return could not be parsed. Value: "400 - Bad request response" is wrong'),
+    chalk.yellow('[express-jsdoc-swagger] Entity: @return could not be parsed. Value: "400 - Bad request response" is wrong'),
   );
 });
 
@@ -44,11 +44,11 @@ test('should give a nice error message for parameters', async () => {
   expect(console.warn).toHaveBeenCalledTimes(2);
   expect(console.warn).toHaveBeenNthCalledWith(
     1,
-    chalk.yellow('Entity: @param could not be parsed. Value: "name.query.required" is wrong'),
+    chalk.yellow('[express-jsdoc-swagger] Entity: @param could not be parsed. Value: "name.query.required" is wrong'),
   );
   expect(console.warn).toHaveBeenNthCalledWith(
     2,
-    chalk.yellow('Entity: @param could not be parsed. Value: "phone.param" is wrong'),
+    chalk.yellow('[express-jsdoc-swagger] Entity: @param could not be parsed. Value: "phone.param" is wrong'),
   );
 });
 
@@ -69,6 +69,6 @@ test('should give a nice error message for requestBody', async () => {
   expect(console.warn).toHaveBeenCalledTimes(1);
   expect(console.warn).toHaveBeenNthCalledWith(
     1,
-    chalk.yellow('If you want to add one @param as body you must provide "request.body" instead of body.body.required'),
+    chalk.yellow('[express-jsdoc-swagger] If you want to add one @param as body you must provide "request.body" instead of body.body.required'),
   );
 });

transforms/paths/parameters.js

@@ -1,5 +1,4 @@
-const chalk = require('chalk');
-
+const errorMessage = require('../utils/errorMessage');
 const setProperty = require('../utils/setProperty')('parameter');
 const formatDescription = require('../utils/formatDescription');
 const getSchema = require('./schema');
@@ -36,8 +35,7 @@ const parameterPayload = (options, schema) => ({
 
 const wrongInOption = paramValue => {
   if (!paramValue.includes('request.body')) {
-    // eslint-disable-next-line
-    console.warn(chalk.yellow(`If you want to add one @param as body you must provide "request.body" instead of ${paramValue}`));
+    errorMessage(`If you want to add one @param as body you must provide "request.body" instead of ${paramValue}`);
   }
   return defaultParseParameter;
 };

transforms/paths/responses.js

@@ -1,5 +1,4 @@
-const chalk = require('chalk');
-
+const errorMessage = require('../utils/errorMessage');
 const STATUS_CODES = require('./validStatusCodes');
 const mapDescription = require('../utils/mapDescription');
 const getContent = require('./content')('@return');
@@ -9,8 +8,7 @@ const hasOldContent = (value, status) => (value[status] && value[status].content
 const formatResponses = values => values.reduce((acc, value) => {
   const [status, description, contentType] = mapDescription(value.description);
   if (!STATUS_CODES[status]) {
-    // eslint-disable-next-line
-    console.warn(chalk.yellow(`Status ${status} is not valid to create a response`));
+    errorMessage(`Status ${status} is not valid to create a response`);
     return {};
   }
   return {

transforms/paths/schema.js

@@ -1,13 +1,11 @@
-const chalk = require('chalk');
-
+const errorMessage = require('../utils/errorMessage');
 const combineSchema = require('../utils/combineSchema');
 const addEnumValues = require('../utils/enumValues');
 const { refSchema, formatRefSchema } = require('../utils/refSchema');
 
 const getSchema = (entity, message) => (type, enumValues = []) => {
   if (!type) {
-    // eslint-disable-next-line
-    return console.warn(chalk.yellow(`Entity: ${entity} could not be parsed. Value: "${message}" is wrong`));
+    return errorMessage(`Entity: ${entity} could not be parsed. Value: "${message}" is wrong`);
   }
   const nameType = type.name;
   let schema = {

transforms/utils/combineSchema.js

@@ -1,4 +1,4 @@
-const chalk = require('chalk');
+const errorMessage = require('./errorMessage');
 const { refSchema } = require('./refSchema');
 
 const VALID_TYPES = ['oneOf', 'anyOf', 'allOf'];
@@ -15,8 +15,7 @@ const combineSchema = elements => {
       [schemaType]: types.map(type => refSchema(type.name)),
     };
   } else {
-    // eslint-disable-next-line
-    console.warn(chalk.yellow(`SchemaType ${schemaType} invalid, it should be one of these ${VALID_TYPES.join(', ')}`));
+    errorMessage(`SchemaType ${schemaType} invalid, it should be one of these ${VALID_TYPES.join(', ')}`);
   }
   return schema;
 };

transforms/utils/errorMessage.js

@@ -0,0 +1,8 @@
+const chalk = require('chalk');
+
+const errorMessage = message => {
+  // eslint-disable-next-line
+  console.warn(chalk.yellow(`[express-jsdoc-swagger] ${message}`));
+};
+
+module.exports = errorMessage;

transforms/utils/setProperty.js

@@ -1,10 +1,9 @@
-const chalk = require('chalk');
+const errorMessage = require('./errorMessage');
 
 const setProperty = entity => {
   const requiredError = (key, item) => new Error(`Key ${key} is required in item ${JSON.stringify(item)} for Entity ${entity}`);
 
-  // eslint-disable-next-line
-  const warnType = (type, value) => console.warn(chalk.yellow(`${type} is not valid with value ${value} for Entity ${entity}`));
+  const warnType = (type, value) => errorMessage(`${type} is not valid with value ${value} for Entity ${entity}`);
 
   return (item, key, options) => {
     if (!item || !key || !options) {