feat(markdownbuilder): create an option to skip any property in markdown #243

Author: florevallatmrf

lib/index.js

@@ -99,7 +99,12 @@ async function main(args) {
     .alias('h', 'header')
     .boolean('h')
     .describe('h', 'if the value is false the header will be skipped')
-    .default('h', true);
+    .default('h', true)
+
+    .alias('s', 'skip')
+    .array('s')
+    .describe('s', 'name of a default property to skip in markdown (may be used multiple times), e.g. -s typefact -s proptable')
+    .default('s', []);
 
   const docs = pipe(
     iter(argv),
@@ -168,6 +173,7 @@ async function main(args) {
       links: docs,
       includeproperties: argv.p,
       exampleformat: argv.f,
+      skipproperties: argv.s,
       rewritelinks: (origin) => {
         const mddir = argv.o;
         const srcdir = argv.d;

lib/markdownBuilder.js

@@ -30,6 +30,7 @@ function build({
   includeproperties = [],
   rewritelinks = x => x,
   exampleformat = 'json',
+  skipproperties = [],
 } = {}) {
   const formats = {
     'date-time': {
@@ -325,6 +326,9 @@ function build({
    * @param {*} props
    */
   function makeproptable(props = {}, patternProps = {}, additionalProps, required, slugger) {
+    if (skipproperties.includes('proptable')) {
+      return paragraph();
+    }
     const proprows = Object
       .entries(props)
       .map(makepropheader(required, false, slugger));
@@ -362,6 +366,9 @@ function build({
   }
 
   function makearrayfact(items, additional) {
+    if (skipproperties.includes('arrayfact')) {
+      return '';
+    }
     return listItem([
       paragraph([text(i18n`Type: `), text(i18n`an array where each item follows the corresponding schema in the following list:`)]),
       list('ordered',
@@ -463,9 +470,15 @@ function build({
       children.push(listItem(text(i18n`is optional`)));
     }
 
-    children.push(maketypefact(definition));
-    children.push(makenullablefact(definition));
-    children.push(makedefinedinfact(definition));
+    if (!skipproperties.includes('typefact')) {
+      children.push(maketypefact(definition));
+    }
+    if (!skipproperties.includes('nullablefact')) {
+      children.push(makenullablefact(definition));
+    }
+    if (!skipproperties.includes('definedinfact')) {
+      children.push(makedefinedinfact(definition));
+    }
 
     const additionalfacts = includeproperties.map((propname) => {
       if (definition[propname]) {
@@ -524,6 +537,9 @@ function build({
   }
 
   function maketypesection(schema, level = 1) {
+    if (skipproperties.includes('typesection')) {
+      return '';
+    }
     const { children } = maketypefact(schema);
     children[0].children.shift();
     return [

test/fixtures/skipproperties/complete.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Complete JSON Schema",
+  "description": "Testing for skipped props",
+  "type": "object",
+  "properties": {
+      "foo": {
+          "type": "string"
+      },
+      "bar": {
+          "description": "Configures the bar property",
+          "type": "boolean",
+          "default": "true"
+      },
+      "foobar": {
+          "description": "Overwrite the bar value",
+          "examples":[{
+            "bar": "true",
+            "foobar": "no"
+          }],
+          "type": "string",
+          "format": "yes/no"
+      }
+    },
+    "additionalProperties": false,
+    "required": [
+        "bar"
+    ]
+}

test/markdownBuilder.test.js

@@ -402,3 +402,31 @@ Reference this group by using
       .contains('# Simple Schema');
   });
 });
+
+describe('Testing Markdown Builder: Skip properties', () => {
+  let schemas;
+
+  before(async () => {
+    schemas = await loadschemas('skipproperties');
+  });
+
+  it('Skipped properties exist', () => {
+    const builder = build({});
+    const results = builder(schemas);
+
+    assertMarkdown(results.complete)
+      .contains('### bar Type')
+      .contains('| Property          | Type      | Required |')
+      .contains('-   defined in: [Complete JSON Schema]');
+  });
+
+  it('Skips the expected properties', () => {
+    const builder = build({ skipproperties: ['typesection', 'definedinfact', 'proptable'] });
+    const results = builder(schemas);
+
+    assertMarkdown(results.complete)
+      .doesNotContain('### bar Type')
+      .doesNotContain('| Property          | Type      | Required |')
+      .doesNotContain('-   defined in: [Complete JSON Schema]');
+  });
+});

test/testUtils.js

@@ -26,6 +26,11 @@ function assertMarkdown(node) {
     const tester = {};
     tester.contains = (str) => {
       assert.ok(result.indexOf(str) >= 0, `Markdown output does not contain search string "${str}"
+${result}`);
+      return tester;
+    };
+    tester.doesNotContain = (str) => {
+      assert.ok(result.indexOf(str) < 0, `Markdown output contains search string "${str}"
 ${result}`);
       return tester;
     };