fix(cli): escape char sequences for javascript comments

Author: raymondfeng

packages/cli/generators/openapi/index.js

@@ -8,7 +8,7 @@
 const BaseGenerator = require('../../lib/base-generator');
 const {debug, debugJson} = require('./utils');
 const {loadAndBuildSpec} = require('./spec-loader');
-const {validateUrlOrFile} = require('./utils');
+const {validateUrlOrFile, escapeComment} = require('./utils');
 const {getControllerFileName} = require('./spec-helper');
 
 const updateIndex = require('../../lib/update-index');
@@ -135,7 +135,7 @@ module.exports = class OpenApiGenerator extends BaseGenerator {
       if (debug.enabled) {
         debug('Copying artifact to: %s', dest);
       }
-      this.copyTemplatedFiles(source, dest, c);
+      this.copyTemplatedFiles(source, dest, mixinEscapeComment(c));
     }
   }
 
@@ -153,7 +153,7 @@ module.exports = class OpenApiGenerator extends BaseGenerator {
         debug('Copying artifact to: %s', dest);
       }
       const source = m.kind === 'class' ? modelSource : typeSource;
-      this.copyTemplatedFiles(source, dest, m);
+      this.copyTemplatedFiles(source, dest, mixinEscapeComment(m));
     }
   }
 
@@ -173,3 +173,7 @@ module.exports = class OpenApiGenerator extends BaseGenerator {
     if (this.shouldExit()) return;
   }
 };
+
+function mixinEscapeComment(context) {
+  return Object.assign(context, {escapeComment});
+}

packages/cli/generators/openapi/templates/src/controllers/controller-template.ts.ejs

@@ -11,15 +11,15 @@ imports.forEach(i => {
 /**
  * The controller class is generated from OpenAPI spec with operations tagged
  * by <%- tag %>
- * <%- description %>
+ * <%- escapeComment(description) %>
  */
 export class <%- className %> {
   constructor() {}
 
   <%_ for (const m of methods) { -%>
   /**
   <%_ for (const c of m.comments) { -%>
-   * <%- c %>
+   * <%- escapeComment(c) %>
   <%_ } -%>
    */
   <%- m.decoration %>

packages/cli/generators/openapi/templates/src/models/model-template.ts.ejs

@@ -20,7 +20,7 @@ imports.forEach(i => {
 
 /**
  * The model class is generated from OpenAPI schema - <%- name %>
- * <%- description %>
+ * <%- escapeComment(description) %>
  */
 @model({name: '<%- name %>'})
 export class <%- className %> {
@@ -32,7 +32,7 @@ export class <%- className %> {
 
   <%_ for (const p of _properties) { -%>
   /**
-   * <%- p.description || '' %>
+   * <%- escapeComment(p.description) %>
    */
   <%- p.decoration %>
   <%- p.signature %>

packages/cli/generators/openapi/templates/src/models/type-template.ts.ejs

@@ -8,6 +8,7 @@ imports.forEach(i => {
 -%>
 /**
  * The model type is generated from OpenAPI schema - <%- name %>
+ * <%- escapeComment(description) %>
  */
 export type <%- className %> = <%- declaration %>;
 

packages/cli/generators/openapi/utils.js

@@ -170,6 +170,16 @@ function escapePropertyName(name) {
   return name;
 }
 
+/**
+ * Escape a string to be used as a block comment
+ *
+ * @param {string} comment
+ */
+function escapeComment(comment) {
+  comment = comment || '';
+  return comment.replace(/\/\*/g, '\\/*').replace(/\*\//g, '*\\/');
+}
+
 function toJsonStr(val) {
   return json5.stringify(val, null, 2);
 }
@@ -183,6 +193,7 @@ module.exports = {
   camelCase: _.camelCase,
   escapeIdentifier,
   escapePropertyName,
+  escapeComment,
   toJsonStr,
   validateUrlOrFile,
 };

packages/cli/test/fixtures/openapi/3.0/customer.yaml

@@ -14,14 +14,14 @@ paths:
     parameters:
       - name: access-token
         in: query
-        description: Access token
+        description: Access token (/* access_token */)
         required: false
         schema:
           type: string
     get:
       tags:
         - Customer
-      description: Returns all customers
+      description: Returns all customers (/* customers */)
       operationId: getCustomers
       parameters:
         - name: if

packages/cli/test/unit/openapi/controller-spec.unit.js

@@ -23,13 +23,13 @@ describe('openapi to controllers/models', () => {
         imports: ["import {Customer} from '../models/customer.model';"],
         methods: [
           {
-            description: 'Returns all customers',
+            description: 'Returns all customers (/* customers */)',
             comments: [
-              'Returns all customers',
+              'Returns all customers (/* customers */)',
               '\n',
               '@param _if if condition',
               '@param limit maximum number of results to return',
-              '@param accessToken Access token',
+              '@param accessToken Access token (/* access_token */)',
               '@returns customer response',
             ],
             decoration: "@operation('get', '/customers')",
@@ -45,7 +45,7 @@ describe('openapi to controllers/models', () => {
               'Creates a new customer',
               '\n',
               '@param _requestBody Customer to add',
-              '@param accessToken Access token',
+              '@param accessToken Access token (/* access_token */)',
               '@returns customer response',
             ],
             decoration: "@operation('post', '/customers')",

packages/cli/test/unit/openapi/openapi-utils.unit.js

@@ -41,4 +41,11 @@ describe('openapi utils', () => {
     expect(utils.escapePropertyName('customer_id')).to.eql('customer_id');
     expect(utils.escapePropertyName('customerid')).to.eql('customerid');
   });
+
+  it('escapes chars for comments', () => {
+    expect(utils.escapeComment('/* abc */')).to.eql('\\/* abc *\\/');
+    expect(utils.escapeComment('/* abc')).to.eql('\\/* abc');
+    expect(utils.escapeComment('abc */')).to.eql('abc *\\/');
+    expect(utils.escapeComment('abc')).to.eql('abc');
+  });
 });