Fix many bugs related to HTML rendering

Author: fmvilas

lib/beautifier.js

@@ -1,5 +1,6 @@
 const OpenAPISampler = require('openapi-sampler');
 const _ = require('lodash');
+const slugg = require('slugg');
 const md = require('markdown-it')();
 
 const sharedStart = (array) => {
@@ -41,25 +42,31 @@ const resolveAllOf = (schema) => {
 
 const generateExample = schema => OpenAPISampler.sample(schema);
 
+const mdToHTML = (text) => {
+  const finalText = text || '';
+  if (finalText.match(/\n/)) return md.render(finalText);
+  return md.renderInline(finalText);
+};
+
 const beautifySchema = (schema) => {
   resolveAllOf(schema);
+  schema.summaryAsHTML = mdToHTML(schema.summary);
+  schema.descriptionAsHTML = mdToHTML(schema.description);
+
+  if (schema.title) schema.slug = `schema-${slugg(schema.title)}`;
   if (!schema.example) schema.generatedExample = generateExample(schema);
 
-  _.each(schema.properties, (prop) => {
-    if (prop.description) prop.descriptionAsHTML = md.render(prop.description || '');
-    if (prop.properties) beautifySchema(prop);
-  });
-  _.each(schema.additionalProperties, (prop) => {
-    if (prop.description) prop.descriptionAsHTML = md.render(prop.description || '');
-    if (prop.additionalProperties) beautifySchema(prop);
-  });
+  _.each(schema.properties, beautifySchema);
+  _.each(schema.additionalProperties, beautifySchema);
+  if (schema.items) beautifySchema(schema.items);
 
   return schema;
 };
 
-const beautifyOperation = (operation) => {
-  operation.summaryAsHTML = md.render(operation.summary || '');
-  operation.descriptionAsHTML = md.render(operation.description || '');
+const beautifyOperation = (operation, operationName, pathName) => {
+  operation.slug = slugg(`op-${operationName}-${pathName}`);
+  operation.summaryAsHTML = mdToHTML(operation.summary);
+  operation.descriptionAsHTML = mdToHTML(operation.description);
 
   if (operation.requestBody) {
     _.each(operation.requestBody.content, (contentType) => {
@@ -74,17 +81,22 @@ const beautifyOperation = (operation) => {
     operation.parameters.filter(p => p.schema).forEach(param => resolveAllOf(param.schema));
 
     operation.parameters.forEach((param) => {
-      param.descriptionAsHTML = md.render(param.description || '');
+      param.descriptionAsHTML = mdToHTML(param.description);
+      if (param.schema) beautifySchema(param.schema);
     });
   }
 
   if (operation.responses) {
     _.each(operation.responses, (response) => {
-      if (response.content && response.content.schema) {
-        resolveAllOf(response.content.schema);
+      if (response.content) {
+        _.each(response.content, (contentType) => {
+          beautifySchema(contentType.schema);
+        });
       }
-      if (response.headers && response.headers.schema) {
-        resolveAllOf(response.headers.schema);
+      if (response.headers) {
+        _.each(response.headers, (contentType) => {
+          beautifySchema(contentType.schema);
+        });
       }
     });
   }
@@ -104,23 +116,21 @@ const cleanBrackets = text => {
 module.exports = (openapi) => {
   openapi.basePath = openapi.basePath || '';
   openapi.info = openapi.info || {};
-  openapi.info.descriptionAsHTML = md.render(openapi.info.description || '');
+  openapi.info.descriptionAsHTML = mdToHTML(openapi.info.description);
 
   if (!openapi.components) openapi.components = {};
   if (!openapi.components.schemas) {
     openapi.__noSchemas = true;
     openapi.components.schemas = {};
   }
 
-  _.each(openapi.components.schemas, (schema, schemaName) => {
-    openapi.components.schemas[schemaName] = beautifySchema(schema);
-  });
+  _.each(openapi.components.schemas, beautifySchema);
 
   if (openapi.servers) {
     _.each(openapi.servers, server => {
-      server.descriptionAsHTML = md.render(server.description || '');
+      server.descriptionAsHTML = mdToHTML(server.description);
       _.each(server.variables, variable => {
-        variable.descriptionAsHTML = md.render(variable.description || '');
+        variable.descriptionAsHTML = mdToHTML(variable.description);
       });
     });
   }
@@ -134,7 +144,7 @@ module.exports = (openapi) => {
         throw new Error(`Security definition "${name}" is not in included in #/components/securitySchemes.`);
       }
 
-      openapi.components.securitySchemes[name].descriptionAsHTML = md.render(openapi.components.securitySchemes[name].description || '');
+      openapi.components.securitySchemes[name].descriptionAsHTML = mdToHTML(openapi.components.securitySchemes[name].description);
       openapi._security.push(openapi.components.securitySchemes[name]);
     });
   }
@@ -153,7 +163,7 @@ module.exports = (openapi) => {
     const httpMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'COPY', 'HEAD', 'OPTIONS', 'LINK', 'UNLIK', 'PURGE', 'LOCK', 'UNLOCK', 'PROPFIND'];
 
     _.each(path, (operation, operationName) => {
-      if (httpMethods.includes(operationName.toUpperCase())) beautifyOperation(operation);
+      if (httpMethods.includes(operationName.toUpperCase())) beautifyOperation(operation, operationName, pathName);
     });
   });
 

package-lock.json

@@ -56,6 +56,7 @@
     "oas-validator": "^1.1.7",
     "openapi-sampler": "^1.0.0-beta.13",
     "project-name-generator": "2.1.1",
+    "slugg": "^1.2.1",
     "word-wrap": "1.1.0"
   }
 }

package.json

@@ -1,3 +1,5 @@
+<a id="{{operation.slug}}" />
+
 {{#if operation.summary}}
 > {{{operation.summary}}}
 

templates/markdown/.partials/operation.md

@@ -1,13 +1,17 @@
 <tr>
   <td>{{tree path}}{{propName}} {{#if required}}<strong>(required)</strong>{{/if}}</td>
   <td>
-    {{prop.type}}
-    {{~#if prop.anyOf}}anyOf{{~/if}}
-    {{~#if prop.oneOf}}oneOf{{~/if}}
-    {{~#if prop.items.type}}({{prop.items.type}}){{~/if}}
+    {{#if prop.schema}}
+    {{prop.schema.type}}
+    {{~#if prop.schema.anyOf}}anyOf{{~/if}}
+    {{~#if prop.schema.oneOf}}oneOf{{~/if}}
+    {{~#if prop.schema.items.type}}({{prop.schema.items.type}}){{~/if}}
+    {{else}}
+    unknown
+    {{/if}}
   </td>
   <td>{{prop.in}}</td>
-  <td>{{{prop.schema.description}}}</td>
+  <td>{{{prop.descriptionAsHTML}}}</td>
   <td>{{{acceptedValues prop.enum}}}</td>
 </tr>
 {{#each prop.anyOf}}

templates/markdown/.partials/param-prop.md

@@ -6,7 +6,7 @@
     {{~#if prop.oneOf}}oneOf{{~/if}}
     {{~#if prop.items.type}}({{prop.items.type}}){{~/if}}
   </td>
-  <td>{{{prop.description}}}</td>
+  <td>{{{prop.descriptionAsHTML}}}</td>
   <td>{{{acceptedValues prop.enum}}}</td>
 </tr>
 {{#each prop.anyOf}}

templates/markdown/.partials/schema-prop.md

@@ -1,3 +1,5 @@
+{{#if renderSlug}}<a id="{{schema.slug}}" />{{/if}}
+
 {{#unless hideTitle}}
 {{#if schema.title}}
 #### {{schema.title}}

templates/markdown/.partials/schema.md

@@ -2,6 +2,6 @@
 ## Schemas
 
 {{#each openapi.components.schemas}}
-  {{~>schema schema=. schemaName=@key~}}
+  {{~>schema schema=. schemaName=@key renderSlug=true~}}
 {{/each}}
 {{/if}}

templates/markdown/.partials/schemas.md

@@ -1,6 +1,6 @@
 # {{swagger.info.title}}
 
-{{{swagger.info.description}}}
+{{{swagger.info.descriptionAsHTML}}}
 
 ## Table of Contents
 
@@ -12,9 +12,23 @@
 {{/if}}
 {{#if openapi.paths}}
 * [Paths](#paths)
+{{#each openapi.paths as |path pathName|}}
+{{#each path as |op opName|}}
+{{#validMethod opName}}
+  - [`{{uppercase opName}}` {{pathName}}](#{{op.slug}})
+{{/validMethod}}
+{{/each}}
+{{/each}}
 {{/if}}
 {{#if openapi.components.schemas}}
 * [Schemas](#schemas)
+{{#each openapi.components.schemas as |schema schemaName|}}
+{{#if schema.slug}}
+  - [{{schema.title}}](#{{schema.slug}})
+{{else}}
+  - {{schema.title}}
+{{/if}}
+{{/each}}
 {{/if}}
 
 {{> info}}