express-jsdoc-swagger - npm Package Compare versions

Comparing version 1.1.0 to 1.1.1

examples/responses/withExamples.js

@@ -33,3 +33,3 @@ const express = require('express');
  * GET /api/v1/pet
- * @return {Pet[]} 200 - success response
+ * @return {array<Pet>} 200 - success response
  * @return {object} 403 - forbidden request response
@@ -36,0 +36,0 @@ * @example response - 200 - example success response

package.json

 {
   "name": "express-jsdoc-swagger",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Swagger OpenAPI 3.x generator",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -167,2 +167,3 @@ ![npm](https://img.shields.io/npm/v/express-jsdoc-swagger)
     <td align="center"><a href="https://github.com/LonelyPrincess"><img src="https://avatars1.githubusercontent.com/u/17673317?v=4" width="100px;" alt=""/><br /><sub><b>Sara Hernández</b></sub></a><br /><a href="https://github.com/BRIKEV/express-jsdoc-swagger/commits?author=LonelyPrincess" title="Code">💻</a></td>
+    <td align="center"><a href="http://servatj.me"><img src="https://avatars0.githubusercontent.com/u/3521485?v=4" width="100px;" alt=""/><br /><sub><b>Josep Servat</b></sub></a><br /><a href="https://github.com/BRIKEV/express-jsdoc-swagger/commits?author=servatj" title="Code">💻</a></td>
   </tr>
@@ -169,0 +170,0 @@ </table>

test/transforms/paths/responses.test.js

@@ -369,2 +369,129 @@ const jsdocInfo = require('../../../consumers/jsdocInfo');
   });
+  it('should parse undefined if example has no valid types (request or response)', () => {
+    const jsdocInput = [`
+      /**
+       * GET /api/v1
+       * @summary This is the summary or description of the endpoint
+       * @return {Song} 200 - success response - application/json
+       * @return {object} 403 - forbidden response - application/json
+       * @example response - 200 - example success response
+       * {
+       *   "title": "untitled song",
+       *   "artist": "anonymous"
+       * }
+       * @example res - 403 - example error response
+       * {
+       *   "error": "failed to retrieve results"
+       * }
+       */
+    `];
+    const expected = {
+      paths: {
+        '/api/v1': {
+          get: {
+            deprecated: false,
+            summary: 'This is the summary or description of the endpoint',
+            parameters: [],
+            tags: [],
+            security: [],
+            responses: {
+              200: {
+                description: 'success response',
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Song',
+                    },
+                    examples: {
+                      example1: {
+                        summary: 'example success response',
+                        value: '{\n  "title": "untitled song",\n  "artist": "anonymous"\n}',
+                      },
+                    },
+                  },
+                },
+              },
+              403: {
+                description: 'forbidden response',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                    },
+                    examples: undefined,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    const parsedJSDocs = jsdocInfo()(jsdocInput);
+    const result = setPaths({}, parsedJSDocs);
+    expect(result).toEqual(expected);
+  });
+  it('should not parse an example if has no valid status', () => {
+    const jsdocInput = [`
+      /**
+       * GET /api/v1
+       * @summary This is the summary or description of the endpoint
+       * @return {Song} 200 - success response - application/json
+       * @return {object} 403 - forbidden response - application/json
+       * @example response - 200 - example success response
+       * {
+       *   "title": "untitled song",
+       *   "artist": "anonymous"
+       * }
+       * @example response - 333 - example error response
+       * {
+       *   "error": "failed to retrieve results"
+       * }
+       */
+    `];
+    const expected = {
+      paths: {
+        '/api/v1': {
+          get: {
+            deprecated: false,
+            summary: 'This is the summary or description of the endpoint',
+            parameters: [],
+            tags: [],
+            security: [],
+            responses: {
+              200: {
+                description: 'success response',
+                content: {
+                  'application/json': {
+                    schema: {
+                      $ref: '#/components/schemas/Song',
+                    },
+                    examples: {
+                      example1: {
+                        summary: 'example success response',
+                        value: '{\n  "title": "untitled song",\n  "artist": "anonymous"\n}',
+                      },
+                    },
+                  },
+                },
+              },
+              403: {
+                description: 'forbidden response',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    const parsedJSDocs = jsdocInfo()(jsdocInput);
+    const result = setPaths({}, parsedJSDocs);
+    expect(result).toEqual(expected);
+  });
 });

transforms/paths/examples.js

@@ -5,2 +5,3 @@ const STATUS_CODES = require('./validStatusCodes');
 const mapDescription = require('../utils/mapDescription');
+const generator = require('../utils/generator');
 
@@ -20,2 +21,7 @@ const REQUEST_BODY = 'request';
 
+const showError = message => {
+  errorMessage(message);
+  return {};
+};
+
 // Generates a new object with information on a response body example
@@ -25,4 +31,3 @@ const parseResponsePayloadExample = (description, content) => {
   if (!STATUS_CODES[status]) {
-    errorMessage(`${status} is not a valid status for a response`);
-    return {};
+    return showError(`${status} is not a valid status for a response`);
   }
@@ -37,2 +42,11 @@ return {
 
+const getParsedExample = ({ type, metadata, content }) => {
+  const types = {
+    [REQUEST_BODY]: () => parseRequestPayloadExample(metadata, content),
+    [RESPONSE_BODY]: () => parseResponsePayloadExample(metadata, content),
+    default: () => showError(`Cannot determine where to use example of type ${type}`),
+  };
+  return (types[type] || types.default)();
+};
+
 /**
@@ -61,11 +75,4 @@ *  Parses a single example tag contents. Depending on the type (response or
 
-  switch (type) {
-    case REQUEST_BODY:
-      return parseRequestPayloadExample(metadata, content);
-    case RESPONSE_BODY:
-      return parseResponsePayloadExample(metadata, content);
-    default:
-      errorMessage(`Cannot determine where to use example of type ${type}`);
-      return {};
-  }
+  const example = getParsedExample({ type, metadata, content });
+  return example;
 };
@@ -95,8 +102,4 @@
  */
-const examplesGenerator = (exampleTags = []) => {
-  if (!exampleTags || !Array.isArray(exampleTags)) return [];
-  const examples = exampleTags.map(parseExample).filter(example => example.type);
-  return examples;
-};
+const exampleGenerator = generator(parseExample, 'type');
 
-module.exports = examplesGenerator;
+module.exports = exampleGenerator;

transforms/paths/formParams.js

@@ -7,9 +7,6 @@ const merge = require('merge');
 
-const formParams = (currentState, key, body, isRequired, requestExamples) => {
-  const bodyType = { name: 'object' };
-  const [description, contentType] = mapDescription(body.description);
-  let requiredValues = isRequired ? [key] : [];
+const getRequiredValues = (currentState, contentType, key, isRequired) => {
   const paramContentType = contentType || DEFAULT_CONTENT_TYPE;
   if (currentState.content[paramContentType]) {
-    requiredValues = [
+    return [
       ...(currentState.content[paramContentType].schema.required || []),
@@ -19,2 +16,7 @@ key,
   }
+  return isRequired ? [key] : [];
+};
+
+const formParams = (currentState, key, body, isRequired, requestExamples) => {
+  const [description, contentType] = mapDescription(body.description);
   const schema = {
@@ -27,3 +29,3 @@ properties: {
     },
-    required: requiredValues,
+    required: getRequiredValues(currentState, contentType, key, isRequired),
   };
@@ -35,3 +37,3 @@ return {
         currentState.content,
-        getContent(bodyType, contentType, description, requestExamples, schema),
+        getContent({ name: 'object' }, contentType, description, requestExamples, schema),
       ),
@@ -38,0 +40,0 @@ },

transforms/paths/parameters.js

@@ -5,2 +5,3 @@ const errorMessage = require('../utils/errorMessage');
 const getSchema = require('./schema');
+const generator = require('../utils/generator');
 
@@ -67,8 +68,2 @@ const REQUIRED = 'required';
 
-const parametersGenerator = (paramValues = []) => {
-  if (!paramValues || !Array.isArray(paramValues)) return [];
-  const params = paramValues.map(parseParameter).filter(param => param.name);
-  return params;
-};
-
-module.exports = parametersGenerator;
+module.exports = generator(parseParameter, 'name');

transforms/paths/requestBody.js

@@ -18,2 +18,7 @@ const setProperty = require('../utils/setProperty')('parameter');
 
+const checkExamples = examples => {
+  const isExample = Array.isArray(examples) && examples.length > 0;
+  return isExample ? formatExamples(examples) : undefined;
+};
+
 const parseBodyParameter = (currentState, body, examples) => {
@@ -24,15 +29,6 @@ const [name, ...extraOptions] = body.name.split('.');
   const [description, contentType] = mapDescription(body.description);
-  const options = {
-    name,
-    required: isRequired,
-    description,
-  };
+  const options = { name, required: isRequired, description };
 
-  let requestExamples;
-  if (Array.isArray(examples) && examples.length > 0) {
-    requestExamples = formatExamples(examples);
-  }
-
   if (hasForm) {
-    return formParams(currentState, name, body, isRequired, requestExamples);
+    return formParams(currentState, name, body, isRequired, checkExamples(examples));
   }
@@ -51,3 +47,3 @@
       ...currentState.content,
-      ...getContent(body.type, contentType, body.description, requestExamples),
+      ...getContent(body.type, contentType, body.description, checkExamples(examples)),
     },
@@ -54,0 +50,0 @@ };

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

243356

increased by14.32%

Number of package files

122

increased by5.17%

Lines of code

7163

increased by10.88%

Number of lines in readme file

176

increased by0.57%

No dependency changes