Merge pull request #53 from tomcollins/copy-additional-properties-from-ref

Improve rendering of $ref links and objects with child properties.

Author: tomcollins

lib/merger.js

@@ -39,8 +39,8 @@ const resolveRef = (
   if (resolvedRef.$ref) {
     // @todo technically this could also require resolution
     mergedProperty.$ref = resolvedRef.$ref;
-    // @todo technically this could also require resolution
   } else {
+    // @todo technically this could also require resolution
     mergedProperty.$ref = ref;
   }
   if (resolvedRef.items && resolvedRef.items.$ref) {

lib/renderer-markdown.js

@@ -25,7 +25,15 @@ const refToLink = (ref, label) => {
   let filename = refParts[refParts.length - 1];
   filename = filename.substr(0, filename.length - 5);
 
-  filename = ref.replace(".json", ".html");
+  filename = ref.replace(".json", ".html").replace(".yml", ".html");
+
+  // if we have a definition copnvert it to a html anchor to the property
+  filenameParts = filename.split("#");
+
+  if (filenameParts.length === 2 && filenameParts[1].match(/^\/definitions/)) {
+    filename =
+      filenameParts[0] + "#" + filenameParts[1].replace("/definitions/", "");
+  }
 
   label = label || filename;
   label = typeToLinkLabel(label, ref);
@@ -70,16 +78,36 @@ Handlebars.registerHelper("enumValues", function (enums) {
   return new Handlebars.SafeString(html + "</ul>");
 });
 
+Handlebars.registerHelper("isDefined", function (value) {
+  return value !== undefined;
+});
+
+Handlebars.registerHelper("isArrayOfStringLikeValues", function (value) {
+  return Array.isArray(value) && !value.find((v) => typeof v === "object");
+});
+
 Handlebars.registerHelper("jsonSchemaType", function (property) {
   return new Handlebars.SafeString(jsonSchemaType(property));
 });
 
+Handlebars.registerHelper("isExternalRef", function (value) {
+  return (
+    typeof value === "string" &&
+    (value.match(/^(.+)#/) || value.match(/^(.+)\.(json|yml)$/))
+  );
+});
+Handlebars.registerHelper("refToLink", function (ref, label) {
+  return refToLink(ref, label);
+});
+
 const attributeRow = (name, property) => {
   let html =
     "<tr>" +
-    '<td colspan="2">' +
+    '<td colspan="2"><a href="#' +
+    name.toLowerCase() +
+    '">' +
     name +
-    "</td>" +
+    "</a></td>" +
     "<td>" +
     jsonSchemaType(property) +
     "</td>" +

package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-schema-static-docs",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "",
   "main": "lib/json-schema-static-docs.js",
   "bin": {

templates/schema.hbs

@@ -30,28 +30,41 @@
 
 {{#each schema.properties}}
 
-## {{ @key }}
-
-{{> property }}
+{{> property propertyKey=@key }}
 
 {{/each}}
 
+
+
+
 {{#*inline "property"}}
 
+{{#if (isDefined parentKey)}}
+  ### {{ parentKey }}.{{ propertyKey }}
+{{else}}
+  ## {{ propertyKey }}
+{{/if}}
+
+{{#if (isExternalRef this.$ref)}}
+  <p>Defined in {{{ refToLink this.$ref this.$ref }}}</p>
+{{/if}}
+
+
 {{#if this.description}}<p>{{ this.description }}</p>{{/if}}
 
 {{> propertyTable}}
 
+{{#unless (isDefined this.$ref)}}
 {{#if this.properties}}
-
 {{#each this.properties}}
-### {{ @key }}
-{{> property }}
+{{> property parentKey=../propertyKey propertyKey=@key }}
 {{/each}}
-
 {{/if}}
+{{/unless}}
+
 {{/inline}}
 
+
 {{#*inline "propertyTable"}}
 <table>
   <thead>
@@ -61,14 +74,18 @@
     </tr>
   </thead>
   <tbody>
+    {{#if this.title}}
     <tr>
       <td>Title</td>
       <td colspan="2">{{ this.title }}</td>
     </tr>
+    {{/if}}
+    {{#if (isDefined this.isRequired)}}
     <tr>
       <td>Required</td>
       <td colspan="2">{{#if this.isRequired}}Yes{{else}}No{{/if}}</td>
     </tr>
+    {{/if}}
     {{propertyTypeRow this }}
     {{#if this.enum}}<tr>
       <td>Enum</td>
@@ -86,6 +103,10 @@
       <td>Pattern</td>
       <td colspan="2">{{this.pattern}}</td>
     </tr>{{/if}}
+    {{!-- {{#if (isArrayOfStringLikeValues this.examples) }}<tr>
+      <td>Examples</td>
+      <td colspan="2"><ul>{{#each this.examples}}<li>{{ this }}</li>{{/each}}</ul></td>
+    </tr>{{/if}} --}}
   </tbody>
 </table>
 {{/inline}}

tests/renderer-markdown.test.js

@@ -65,9 +65,9 @@ test("renders attributes", async () => {
   let expectedText =
     "## Attributes\n\n" +
     '<table><thead><tr><th colspan="2">Name</th><th>Type</th></tr></thead>' +
-    '<tr><td colspan="2">property1</td><td>String</td></tr>' +
-    '<tr><td colspan="2">property2</td><td>[string, integer]</td></tr>' +
-    '<tr><td colspan="2">property3</td><td>Array [<a href="property3.html">Property3.html</a>]</td></tr>' +
+    '<tr><td colspan="2"><a href="#property1">property1</a></td><td>String</td></tr>' +
+    '<tr><td colspan="2"><a href="#property2">property2</a></td><td>[string, integer]</td></tr>' +
+    '<tr><td colspan="2"><a href="#property3">property3</a></td><td>Array [<a href="property3.html">Property3.html</a>]</td></tr>' +
     "</tbody></table>";
 
   expect(result).toEqual(expect.stringContaining(expectedText));
@@ -92,19 +92,19 @@ test("renders string property enums", async () => {
 });
 
 test("renders array property types", async () => {
-  expect.assertions(1);
+  expect.assertions(2);
   rendererMarkdown = new RendererMarkdown(defaultTemplatePath);
   await rendererMarkdown.setup();
   let result = rendererMarkdown.renderSchema(mergedSchema);
 
   result = result.match(/## property3(.*\n)*/)[0];
   result = removeFormatting(result);
 
-  let expectedText =
-    "" +
-    '<tr><td>Title</td><td colspan="2">Property 3</td></tr>' +
-    '<tr><td>Required</td><td colspan="2">No</td></tr>' +
+  let expectedTitle = '<tr><td>Title</td><td colspan="2">Property 3</td></tr>';
+  expect(result).toEqual(expect.stringContaining(expectedTitle));
+
+  let expectedType =
     '<tr><td>Type</td><td colspan="2">Array [<a href="property3.html">Property3.html</a>]</td></tr>';
 
-  expect(result).toEqual(expect.stringContaining(expectedText));
+  expect(result).toEqual(expect.stringContaining(expectedType));
 });