Escape */ sequences in generated JSDoc to prevent comment injection

.changeset/late-bottles-reply.md

@@ -0,0 +1,5 @@
+---
+"swagger-typescript-api": patch
+---
+
+Escape `*/` sequences in generated JSDoc content to prevent comment injection from OpenAPI fields.

src/code-gen-process.ts

@@ -235,6 +235,8 @@ export class CodeGenProcess {
         Ts: this.config.Ts,
         formatDescription:
           this.schemaParserFabric.schemaFormatters.formatDescription,
+        escapeJSDocContent:
+          this.schemaParserFabric.schemaFormatters.escapeJSDocContent,
         internalCase: camelCase,
         classNameCase: pascalCase,
         pascalCase: pascalCase,

src/schema-parser/schema-formatters.ts

@@ -30,10 +30,17 @@ export class SchemaFormatters {
         };
       }
 
+      const escapedContent = parsedSchema.content.map((item) => ({
+        ...item,
+        description: item.description
+          ? this.escapeJSDocContent(item.description)
+          : "",
+      }));
+
       return {
         ...parsedSchema,
         $content: parsedSchema.content,
-        content: this.config.Ts.EnumFieldsWrapper(parsedSchema.content),
+        content: this.config.Ts.EnumFieldsWrapper(escapedContent),
       };
     },
     [SCHEMA_TYPES.OBJECT]: (parsedSchema) => {
@@ -103,20 +110,34 @@ export class SchemaFormatters {
     return formatterFn?.(parsedSchema) || parsedSchema;
   };
 
-  formatDescription = (description: string | undefined, inline?: boolean) => {
+  // OpenAPI fields are untrusted input that may contain `*/` which would
+  // prematurely close JSDoc block comments in generated TypeScript output.
+  // Note: only `undefined` maps to empty string; `null` is preserved as "null"
+  // because `@default null` is a valid JSDoc annotation for nullable fields.
+  escapeJSDocContent = (content: unknown): string => {
+    if (content === undefined) return "";
+    const str = typeof content === "string" ? content : String(content);
+    return str.replace(/\*\//g, "*\\/");
+  };
+
+  formatDescription = (
+    description: string | undefined,
+    inline?: boolean,
+  ): string => {
     if (!description) return "";
 
-    const hasMultipleLines = description.includes("\n");
+    const escapedDescription = this.escapeJSDocContent(description);
+    const hasMultipleLines = escapedDescription.includes("\n");
 
-    if (!hasMultipleLines) return description;
+    if (!hasMultipleLines) return escapedDescription;
 
     if (inline) {
-      return compact(description.split(/\n/g).map((part) => part.trim())).join(
-        " ",
-      );
+      return compact(
+        escapedDescription.split(/\n/g).map((part) => part.trim()),
+      ).join(" ");
     }
 
-    return description.replace(/\n$/g, "");
+    return escapedDescription.replace(/\n$/g, "");
   };
 
   formatObjectContent = (content) => {

templates/base/data-contract-jsdoc.ejs

@@ -1,27 +1,27 @@
 <%
 const { data, utils } = it;
-const { formatDescription, require, _ } = utils;
+const { formatDescription, escapeJSDocContent, require, _ } = utils;
 
 const stringify = (value) => _.isObject(value) ? JSON.stringify(value) : _.isString(value) ? `"${value}"` : value;
 
 const jsDocLines = _.compact([
-    data.title,
+    data.title && formatDescription(data.title),
     data.description && formatDescription(data.description),
     !_.isUndefined(data.deprecated) && data.deprecated && '@deprecated',
-    !_.isUndefined(data.format) && `@format ${data.format}`,
-    !_.isUndefined(data.minimum) && `@min ${data.minimum}`,
-    !_.isUndefined(data.multipleOf) && `@multipleOf ${data.multipleOf}`,
-    !_.isUndefined(data.exclusiveMinimum) && `@exclusiveMin ${data.exclusiveMinimum}`,
-    !_.isUndefined(data.maximum) && `@max ${data.maximum}`,
-    !_.isUndefined(data.minLength) && `@minLength ${data.minLength}`,
-    !_.isUndefined(data.maxLength) && `@maxLength ${data.maxLength}`,
-    !_.isUndefined(data.exclusiveMaximum) && `@exclusiveMax ${data.exclusiveMaximum}`,
-    !_.isUndefined(data.maxItems) && `@maxItems ${data.maxItems}`,
-    !_.isUndefined(data.minItems) && `@minItems ${data.minItems}`,
-    !_.isUndefined(data.uniqueItems) && `@uniqueItems ${data.uniqueItems}`,
-    !_.isUndefined(data.default) && `@default ${stringify(data.default)}`,
-    !_.isUndefined(data.pattern) && `@pattern ${data.pattern}`,
-    !_.isUndefined(data.example) && `@example ${stringify(data.example)}`
+    !_.isUndefined(data.format) && `@format ${escapeJSDocContent(data.format)}`,
+    !_.isUndefined(data.minimum) && `@min ${escapeJSDocContent(data.minimum)}`,
+    !_.isUndefined(data.multipleOf) && `@multipleOf ${escapeJSDocContent(data.multipleOf)}`,
+    !_.isUndefined(data.exclusiveMinimum) && `@exclusiveMin ${escapeJSDocContent(data.exclusiveMinimum)}`,
+    !_.isUndefined(data.maximum) && `@max ${escapeJSDocContent(data.maximum)}`,
+    !_.isUndefined(data.minLength) && `@minLength ${escapeJSDocContent(data.minLength)}`,
+    !_.isUndefined(data.maxLength) && `@maxLength ${escapeJSDocContent(data.maxLength)}`,
+    !_.isUndefined(data.exclusiveMaximum) && `@exclusiveMax ${escapeJSDocContent(data.exclusiveMaximum)}`,
+    !_.isUndefined(data.maxItems) && `@maxItems ${escapeJSDocContent(data.maxItems)}`,
+    !_.isUndefined(data.minItems) && `@minItems ${escapeJSDocContent(data.minItems)}`,
+    !_.isUndefined(data.uniqueItems) && `@uniqueItems ${escapeJSDocContent(data.uniqueItems)}`,
+    !_.isUndefined(data.default) && `@default ${escapeJSDocContent(stringify(data.default))}`,
+    !_.isUndefined(data.pattern) && `@pattern ${escapeJSDocContent(data.pattern)}`,
+    !_.isUndefined(data.example) && `@example ${escapeJSDocContent(stringify(data.example))}`
 ]).join('\n').split('\n');
 %>
 <% if (jsDocLines.every(_.isEmpty)) { %>

templates/base/object-field-jsdoc.ejs

@@ -1,18 +1,18 @@
 <%
 const { field, utils } = it;
-const { formatDescription, require, _ } = utils;
+const { formatDescription, escapeJSDocContent, require, _ } = utils;
 
 const comments = _.uniq(
     _.compact([
-        field.title,
-        field.description,
+        field.title && formatDescription(field.title),
+        field.description && formatDescription(field.description),
         field.deprecated && ` * @deprecated`,
-        !_.isUndefined(field.format) && `@format ${field.format}`,
-        !_.isUndefined(field.minimum) && `@min ${field.minimum}`,
-        !_.isUndefined(field.maximum) && `@max ${field.maximum}`,
-        !_.isUndefined(field.pattern) && `@pattern ${field.pattern}`,
+        !_.isUndefined(field.format) && `@format ${escapeJSDocContent(field.format)}`,
+        !_.isUndefined(field.minimum) && `@min ${escapeJSDocContent(field.minimum)}`,
+        !_.isUndefined(field.maximum) && `@max ${escapeJSDocContent(field.maximum)}`,
+        !_.isUndefined(field.pattern) && `@pattern ${escapeJSDocContent(field.pattern)}`,
         !_.isUndefined(field.example) &&
-        `@example ${_.isObject(field.example) ? JSON.stringify(field.example) : field.example}`,
+        `@example ${escapeJSDocContent(_.isObject(field.example) ? JSON.stringify(field.example) : field.example)}`,
     ]).reduce((acc, comment) => [...acc, ...comment.split(/\n/g)], []),
 );
 %>

templates/base/route-docs.ejs

@@ -1,24 +1,24 @@
 <%
 const { config, route, utils } = it;
-const { _, formatDescription, fmtToJSDocLine, pascalCase, require } = utils;
+const { _, formatDescription, escapeJSDocContent, fmtToJSDocLine, pascalCase, require } = utils;
 const { raw, request, routeName } = route;
 
 const jsDocDescription = raw.description ?
     ` * @description ${formatDescription(raw.description, true)}` :
     fmtToJSDocLine('No description', { eol: false });
 const jsDocLines = _.compact([
-    _.size(raw.tags) && ` * @tags ${raw.tags.join(", ")}`,
-    ` * @name ${pascalCase(routeName.usage)}`,
-    raw.summary && ` * @summary ${raw.summary}`,
-    ` * @request ${_.upperCase(request.method)}:${raw.route}`,
+    _.size(raw.tags) && ` * @tags ${raw.tags.map((tag) => formatDescription(tag, true)).join(", ")}`,
+    ` * @name ${escapeJSDocContent(pascalCase(routeName.usage))}`,
+    raw.summary && ` * @summary ${formatDescription(raw.summary, true)}`,
+    ` * @request ${escapeJSDocContent(_.upperCase(request.method))}:${escapeJSDocContent(raw.route)}`,
     raw.deprecated && ` * @deprecated`,
-    routeName.duplicate && ` * @originalName ${routeName.original}`,
+    routeName.duplicate && ` * @originalName ${escapeJSDocContent(routeName.original)}`,
     routeName.duplicate && ` * @duplicate`,
     request.security && ` * @secure`,
     ...(config.generateResponses && raw.responsesTypes.length
     ? raw.responsesTypes.map(
         ({ type, status, description, isSuccess }) =>
-            ` * @response \`${status}\` \`${_.replace(_.replace(type, /\/\*/g, "\\*"), /\*\//g, "*\\")}\` ${description}`,
+            ` * @response \`${escapeJSDocContent(status)}\` \`${escapeJSDocContent(type)}\` ${formatDescription(description, true)}`,
         )
     : []),
 ]).map(str => str.trimEnd()).join("\n");

templates/default/api.ejs

@@ -1,24 +1,24 @@
 <%
 const { apiConfig, routes, utils, config } = it;
 const { info, servers, externalDocs } = apiConfig;
-const { _, require, formatDescription } = utils;
+const { _, require, formatDescription, escapeJSDocContent } = utils;
 
 const server = (servers && servers[0]) || { url: "" };
 
 const descriptionLines = _.compact([
-  `@title ${info.title || "No title"}`,
-  info.version && `@version ${info.version}`,
+  `@title ${escapeJSDocContent(info.title || "No title")}`,
+  info.version && `@version ${escapeJSDocContent(info.version)}`,
   info.license && `@license ${_.compact([
-    info.license.name,
-    info.license.url && `(${info.license.url})`,
+    info.license.name && escapeJSDocContent(info.license.name),
+    info.license.url && `(${escapeJSDocContent(info.license.url)})`,
   ]).join(" ")}`,
-  info.termsOfService && `@termsOfService ${info.termsOfService}`,
-  server.url && `@baseUrl ${server.url}`,
-  externalDocs.url && `@externalDocs ${externalDocs.url}`,
+  info.termsOfService && `@termsOfService ${escapeJSDocContent(info.termsOfService)}`,
+  server.url && `@baseUrl ${escapeJSDocContent(server.url)}`,
+  externalDocs.url && `@externalDocs ${escapeJSDocContent(externalDocs.url)}`,
   info.contact && `@contact ${_.compact([
-    info.contact.name,
-    info.contact.email && `<${info.contact.email}>`,
-    info.contact.url && `(${info.contact.url})`,
+    info.contact.name && escapeJSDocContent(info.contact.name),
+    info.contact.email && `<${escapeJSDocContent(info.contact.email)}>`,
+    info.contact.url && `(${escapeJSDocContent(info.contact.url)})`,
   ]).join(" ")}`,
   info.description && " ",
   info.description && _.replace(formatDescription(info.description), /\n/g, "\n * "),