auto sample generation is disable for non-required properties only

Author: aleung

README.md

@@ -52,8 +52,8 @@ Available options:
   Don't include `readOnly` object properties
   - **skipWriteOnly** - `boolean`
   Don't include `writeOnly` object properties
-  - **disableAutoGeneration** - `boolean`
-  Don't auto generate sample when the schema hasn't explicit example nor default value
+  - **disableNonRequiredAutoGen** - `boolean`
+  Don't auto generate sample for non-required object properties when the schema hasn't explicit example nor default value
   - **quiet** - `boolean`
   Don't log console warning messages
 - **spec** - whole specification where the schema is taken from. Required only when schema may contain `$ref`. **spec** must not contain any external references

src/samplers/array.js

@@ -7,7 +7,7 @@ export function sampleArray(schema, options = {}, spec, context) {
     arrayLength = Math.max(arrayLength, schema.items.length);
   }
 
-  let itemSchemaGetter = itemNumber => {
+  const itemSchemaGetter = itemNumber => {
     if (Array.isArray(schema.items)) {
       return schema.items[itemNumber] || {};
     }
@@ -18,9 +18,13 @@ export function sampleArray(schema, options = {}, spec, context) {
   if (!schema.items) return res;
 
   for (let i = 0; i < arrayLength; i++) {
-    let itemSchema = itemSchemaGetter(i);
-    let { value: sample } = traverse(itemSchema, options, spec, {depth: depth + 1});
+    let { value: sample } = traverse(itemSchemaGetter(i), options, spec, {depth: depth + 1});
     res.push(sample);
   }
-  return res;
+
+  if (!options.omissible || res.some(item => item !== null)) {
+    return res;
+  }
+
+  return null;
 }

src/samplers/boolean.js

@@ -1,5 +1,5 @@
-export function sampleBoolean(schema, options) {
-  if (options.disableAutoGeneration) {
+export function sampleBoolean(schema, options={}) {
+  if (options.omissible) {
     return null;
   }
   return true; // let be optimistic :)

src/samplers/number.js

@@ -1,11 +1,10 @@
 export function sampleNumber(schema, options={}) {
-  if (options.disableAutoGeneration) {
+  if (options.omissible) {
     return null;
   }
 
-  let res;
   if (schema.maximum && schema.minimum) {
-    res = schema.exclusiveMinimum ? Math.floor(schema.minimum) + 1 : schema.minimum;
+    let res = schema.exclusiveMinimum ? Math.floor(schema.minimum) + 1 : schema.minimum;
     if ((schema.exclusiveMaximum && res >= schema.maximum) ||
       ((!schema.exclusiveMaximum && res > schema.maximum))) {
       res = (schema.maximum + schema.minimum) / 2;

src/samplers/object.js

@@ -4,19 +4,28 @@ export function sampleObject(schema, options = {}, spec, context) {
   const depth = (context && context.depth || 1);
 
   if (schema && typeof schema.properties === 'object') {
-    let requiredKeys = (Array.isArray(schema.required) ? schema.required : []);
-    let requiredKeyDict = requiredKeys.reduce((dict, key) => {
+    const requiredKeys = (Array.isArray(schema.required) ? schema.required : []);
+    const requiredKeyDict = requiredKeys.reduce((dict, key) => {
       dict[key] = true;
       return dict;
     }, {});
 
     Object.keys(schema.properties).forEach(propertyName => {
+      const isRequired = requiredKeyDict.hasOwnProperty(propertyName);
       // skip before traverse that could be costly
-      if (options.skipNonRequired && !requiredKeyDict.hasOwnProperty(propertyName)) {
+      if (options.skipNonRequired && !isRequired) {
         return;
       }
 
-      const sample = traverse(schema.properties[propertyName], options, spec, { propertyName, depth: depth + 1 });
+      const propertyOmissible = options.disableNonRequiredAutoGen && !isRequired;
+
+      const sample = traverse(
+        schema.properties[propertyName],
+        Object.assign({}, options, { omissible: propertyOmissible }),
+        spec,
+        { propertyName, depth: depth + 1 }
+      );
+
       if (options.skipReadOnly && sample.readOnly) {
         return;
       }
@@ -25,18 +34,18 @@ export function sampleObject(schema, options = {}, spec, context) {
         return;
       }
 
-      if (sample.value || !options.disableAutoGeneration){
+      if (sample.value || !propertyOmissible) {
         res[propertyName] = sample.value;
       }
     });
   }
 
-  if (!options.disableAutoGeneration && schema && typeof schema.additionalProperties === 'object') {
+  if (!options.disableNonRequiredAutoGen && schema && typeof schema.additionalProperties === 'object') {
     res.property1 = traverse(schema.additionalProperties, options, spec, {depth: depth + 1 }).value;
     res.property2 = traverse(schema.additionalProperties, options, spec, {depth: depth + 1 }).value;
   }
 
-  if (Object.keys(res).length > 0 || !options.disableAutoGeneration) {
+  if (Object.keys(res).length > 0 || !options.omissible) {
     return res;
   }
 

src/samplers/string.js

@@ -78,7 +78,7 @@ const stringFormats = {
 };
 
 export function sampleString(schema, options, spec, context) {
-  if (options && options.disableAutoGeneration) {
+  if (options && options.omissible) {
     return null;
   }
   let format = schema.format || 'default';

src/traverse.js

@@ -92,7 +92,7 @@ export function traverse(schema, options, spec, context) {
     example = schema.default;
   } else if (schema.const !== undefined) {
     example = schema.const;
-  } else if (schema.enum !== undefined && schema.enum.length) {
+  } else if (schema.enum !== undefined && schema.enum.length && !options.disableNonRequiredAutoGen) {
     example = schema.enum[0];
   } else if (schema.examples !== undefined && schema.examples.length) {
     example = schema.examples[0];

test/integration.spec.js

@@ -406,9 +406,10 @@ describe('Integration', function() {
       expect(result).to.equal(expected);
     });
 
-    it('should use explicit example', function() {  // TODO: array
+    it('should skip non-required properties without example if disableNonRequiredAutoGen=true', () => {
       var obj = {
         withExample: 'Example',
+        withExampleArray: [3],
       };
       schema = {
         type: 'object',
@@ -425,19 +426,41 @@ describe('Integration', function() {
           withoutExampleObject: {
             type: 'object',
           },
+          withoutExampleArray: {
+            type: 'array',
+            items: { type: 'string'}
+          },
           withExample: {
             type: 'string',
             example: 'Example'
+          },
+          withExampleArray: {
+            type: 'array',
+            items: { type: 'number', default: 3 }
           }
         },
         additionalProperties: {
           type: 'number'
         }
       };
-      result = OpenAPISampler.sample(schema, { disableAutoGeneration: true });
+      result = OpenAPISampler.sample(schema, { disableNonRequiredAutoGen: true });
+      expected = obj;
+      expect(result).to.deep.equal(obj);
+    });
+
+    it('should return empty object if disableNonRequiredAutoGen=true and no explicit example', () => {
+      var obj = {};
+      schema = {
+        type: 'object',
+        properties: {
+          withoutExampleString: { type: 'string' },
+        }
+      };
+      result = OpenAPISampler.sample(schema, { disableNonRequiredAutoGen: true });
       expected = obj;
       expect(result).to.deep.equal(obj);
     });
+
   });
 
   describe('Detection', function() {

test/unit/array.spec.js

@@ -22,4 +22,45 @@ describe('sampleArray', () => {
     res = sampleArray({items: [{type: 'number'}, {type: 'string'}, {}]});
     expect(res).to.deep.equal([0, 'string', null]);
   });
+
+  describe('disableNonRequiredAutoGen', () => {
+
+    it('should return null if omissible=true and primitive type item has no example', () => {
+      res = sampleArray({ items: { type: 'string' } }, { omissible: true, disableNonRequiredAutoGen: true });
+      expect(res).to.be.null;
+    });
+
+    it('should return null if omssible=true and object type item has no example', () => {
+      res = sampleArray({
+        items: {
+          type: 'object',
+          properties: {
+            a: { type: 'string' },
+          },
+        }
+      }, { omissible: true, disableNonRequiredAutoGen: true });
+      expect(res).to.be.null;
+    });
+
+    it('should return valid array samples if omissible=false and primitive type item has no example', () => {
+      // the sample must be valid to schema and show the array item type when the array is not omitted
+      res = sampleArray({ items: { type: 'string' }, minItems: 2 }, { disableNonRequiredAutoGen: true });
+      expect(res).to.deep.equal(['string', 'string']);
+    });
+
+    it('should return array of empty object if omssible=false and object type item has no example', () => {
+      // the sample must be valid to schema and show the array item type when the array is not omitted
+      res = sampleArray({
+        items: {
+          type: 'object',
+          properties: {
+            a: { type: 'string' },
+          },
+        }
+      }, { disableNonRequiredAutoGen: true });
+      expect(res).to.deep.equal([{}]);
+    });
+
+  });
+
 });

test/unit/number.spec.js

@@ -54,8 +54,8 @@ describe('sampleNumber', () => {
     expect(res).to.equal(3);
   });
 
-  it('should return null if disableAutoGeneration is true', () => {
-    res = sampleNumber({}, { disableAutoGeneration: true });
+  it('should return null if it is omissible', () => {
+    res = sampleNumber({}, { omissible: true });
     expect(res).to.be.null;
   });
 });