Sanitize dangerous JSDoc sequences to avoid prematurely closing comments

Author: FDiskas

src/schema-parser/schema-formatters.ts

@@ -105,23 +105,33 @@ export class SchemaFormatters {
   formatDescription = (description, inline) => {
     if (!description) return "";
 
-    const hasMultipleLines = description.includes("\n");
+    // Sanitize dangerous JSDoc sequences to avoid prematurely closing comments
+    // e.g. "**/information**" contains "*/" which ends a JSDoc block
+    const sanitizeForJsDoc = (text: string) =>
+      text
+        // Break the JSDoc terminator so it doesn't end the comment block
+        .replace(/\*\//g, "*\\/");
 
-    if (!hasMultipleLines) return description;
+    const safeDescription = sanitizeForJsDoc(String(description));
+
+    const hasMultipleLines = safeDescription.includes("\n");
+
+    if (!hasMultipleLines) return safeDescription;
 
     if (inline) {
-      return lodash
-        .chain(
-          description
-            .replace(/\//g, "")
-            .split(/\n/g)
-            .map((part) => part.trim()),
-        )
-        .compact()
-        .value();
+      return (
+        lodash
+          // @ts-expect-error TS(2339) FIXME: Property '_' does not exist on type 'LoDashStatic'... Remove this comment to see the full error message
+          ._(safeDescription)
+          .split(/\n/g)
+          .map((part: string) => part.trim())
+          .compact()
+          .join(" ")
+          .valueOf()
+      );
     }
 
-    return description.replace(/\n$/g, "");
+    return safeDescription.replace(/\n$/g, "");
   };
 
   formatObjectContent = (content) => {

tests/spec/descriptionSanitize/basic.test.ts

@@ -0,0 +1,39 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { generateApi } from "../../../src/index.js";
+
+describe("descriptionSanitize", async () => {
+  let tmpdir = "";
+
+  beforeAll(async () => {
+    tmpdir = await fs.mkdtemp(path.join(os.tmpdir(), "swagger-typescript-api"));
+  });
+
+  afterAll(async () => {
+    await fs.rm(tmpdir, { recursive: true });
+  });
+
+  test("route description with JSDoc terminator is escaped", async () => {
+    await generateApi({
+      // Use defaults to generate single Api.ts with client and docs
+      input: path.resolve(import.meta.dirname, "schema.yml"),
+      output: tmpdir,
+      silent: true,
+    });
+
+    const content = await fs.readFile(path.join(tmpdir, "Api.ts"), {
+      encoding: "utf8",
+    });
+
+    // Ensure the potentially dangerous sequence is escaped inside JSDoc
+    expect(content).toContain(
+      "@description Get service point file of all Nordic countries (SE,FI,DK,NO) from S3 storage.",
+    );
+    expect(content).toContain("**\\/information** endpoint");
+
+    // And ensure the raw terminator never appears inside the block
+    expect(content).not.toMatch(/\*\*\//); // "**/" shouldn't be present
+  });
+});

tests/spec/descriptionSanitize/schema.yml

@@ -0,0 +1,33 @@
+openapi: 3.0.3
+info:
+  title: desc-escape
+  version: 0.0.0
+paths:
+  /v5/servicepoints/file/ALL-SE-FI-DK-NO-{date}.json.gz:
+    get:
+      tags:
+        - Service Points File
+      summary: Get service point file of all Nordic countries (SE,FI,DK,NO).
+      description: |-
+        Get service point file of all Nordic countries (SE,FI,DK,NO) from S3 storage. You can download previous service point file upto 7 days from current date. This is equivalent to **/information** endpoint with parameters `countryCode:SE,FI,DK,NO` and `context:ALL` and header `Accept-Encoding:gzip`.
+
+        Download the file using the URL in reponse.
+      operationId: ServicePointFile
+      parameters:
+        - name: date
+          in: path
+          description: Date of file you want to download. Format should be **YYYY-MM-DD**.
+          required: true
+          style: simple
+          explode: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/gzip:
+              schema:
+                type: string
+        '401':
+          description: Authentication token is missing/invalid