fixes #409 - improved summary and description rendering

Author: mrin9

src/templates/endpoint-template.js

@@ -55,7 +55,7 @@ function endpointHeadTemplate(path) {
       : ''
     }
     <div class="only-large-screen" style="min-width:60px; flex:1"></div>
-    <div class="m-markdown-small descr"> ${unsafeHTML(marked(path.summary || ''))} </div>
+    <div class="descr">${path.summary || path.shotSummary} </div>
   </div>
   `;
 }
@@ -81,7 +81,7 @@ function endpointBodyTemplate(path) {
   return html`
   <div class='endpoint-body ${path.method} ${path.deprecated ? 'deprecated' : ''}'>
     <div class="summary">
-      ${path.summary && path.summary !== path.description ? html`<div class="title">${path.summary}</div>` : ''}
+      ${path.summary ? html`<div class="title">${path.summary}<div>` : path.shortSummary !== path.description ? html`<div class="title">${path.shortSummary}</div>` : ''}
       ${path.description ? html`<div class="m-markdown"> ${unsafeHTML(marked(path.description))}</div>` : ''}
       ${pathSecurityTemplate.call(this, path.security)}
       ${codeSampleTabPanel}

src/templates/expanded-endpoint-template.js

@@ -34,19 +34,13 @@ export function expandedEndpointBodyTemplate(path, tagName = '') {
     ${this.renderStyle === 'focused' ? html`<h3 class="upper" style="font-weight:bold"> ${tagName} </h3>` : ''}
     ${path.deprecated ? html`<div class="bold-text red-text"> DEPRECATED </div>` : ''}
     ${html`
-      <h2 class = "${path.deprecated ? 'gray-text' : ''}"> 
-        ${path.summary || html`<span class='upper ${path.deprecated ? ' method-fg gray-text' : path.method}  '> ${path.method}</span> ${path.path}`} 
-      </h2>
-      ${path.summary
-        ? html`
-          <div class='mono-font regular-font-size' style='padding: 8px 0; color:var(--fg3)'> 
-            <span class='regular-font upper method-fg  ${path.deprecated ? ' gray-text' : ` bold-text ${path.method}`} '>${path.method}</span> 
-            <span class = '${path.deprecated ? 'gray-text' : ''}'> ${path.path} </span>
-          </div>`
-        : ''
-      }`
+      <h2> ${path.shortSummary || `${path.method.toUpperCase()} ${path.path}`}</h2>
+      <div class='mono-font regular-font-size' style='padding: 8px 0; color:var(--fg3)'> 
+        <span class='regular-font upper method-fg bold-text ${path.method}'>${path.method}</span> 
+        <span>${path.path}</span>
+      </div>`
     }
-    ${path.description ? html`<div class="m-markdown"> ${unsafeHTML(marked(path.description || ''))}</div>` : ''}
+    ${path.description ? html`<div class="m-markdown"> ${unsafeHTML(marked(path.description))}</div>` : ''}
     ${pathSecurityTemplate.call(this, path.security)}
     ${codeSampleTabPanel}
     <div class='expanded-req-resp-container'>

src/templates/navbar-template.js

@@ -156,7 +156,7 @@ export default function navbarTemplate() {
             <span style = "${p.deprecated ? 'filter:opacity(0.5)' : ''}">
               ${this.usePathInNavBar === 'true'
                 ? html`<span class='mono-font'>${p.method.toUpperCase()} ${p.path}</span>`
-                : p.summary
+                : p.summary || p.shortSummary
               }
             </span>
           </div>`)}

src/utils/spec-parser.js

@@ -278,8 +278,8 @@ function groupByTags(openApiSpec, sortTags = false, sortEndpointsBy) {
   for (const path in openApiSpec.paths) {
     const commonParams = openApiSpec.paths[path].parameters;
     const commonPathProp = {
-      summary: openApiSpec.paths[path].summary,
-      description: openApiSpec.paths[path].description,
+      // summary: openApiSpec.paths[path].summary,
+      // description: openApiSpec.paths[path].description,
       servers: openApiSpec.paths[path].servers ? openApiSpec.paths[path].servers : [],
       parameters: openApiSpec.paths[path].parameters ? openApiSpec.paths[path].parameters : [],
     };
@@ -321,15 +321,11 @@ function groupByTags(openApiSpec, sortTags = false, sortEndpointsBy) {
             tags.push(tagObj);
           }
 
-          // Generate Path summary and Description if it is missing for a method
-          let summary = (fullPath.summary || fullPath.description || `${methodName} ${path}`).trim().split('/\r?\n/')[0];
-          if (summary.length > 100) {
-            summary = summary.split('.')[0];
+          // Generate a short summary which is broken
+          let shortSummary = (fullPath.summary || fullPath.description || fullPath.path).trim();
+          if (shortSummary.length > 100) {
+            shortSummary = shortSummary.split('/\r?\n|[.]/')[0]; // take the first line (period or carriage return)
           }
-          if (!fullPath.description) {
-            fullPath.description = ((fullPath.summary || '-').trim());
-          }
-
           // Merge Common Parameters with This methods parameters
           let finalParameters = [];
           if (commonParams) {
@@ -351,9 +347,10 @@ function groupByTags(openApiSpec, sortTags = false, sortEndpointsBy) {
             show: true,
             expanded: false,
             expandedAtLeastOnce: false,
-            summary,
+            summary: (fullPath.summary || ''),
+            description: (fullPath.description || ''),
+            shortSummary,
             method: methodName,
-            description: fullPath.description,
             path,
             operationId: fullPath.operationId,
             elementId: `${methodName}-${path.replace(invalidCharsRegEx, '-')}`,
@@ -364,8 +361,8 @@ function groupByTags(openApiSpec, sortTags = false, sortEndpointsBy) {
             callbacks: fullPath.callbacks,
             deprecated: fullPath.deprecated,
             security: fullPath.security,
-            commonSummary: commonPathProp.summary,
-            commonDescription: commonPathProp.description,
+            // commonSummary: commonPathProp.summary,
+            // commonDescription: commonPathProp.description,
             xCodeSamples: fullPath['x-codeSamples'] || fullPath['x-code-samples'] || '',
           });
         });// End of tag path create