Escape */ sequences in generated JSDoc to prevent comment injection

[smorimoto]

Problem

OpenAPI specification fields (descriptions, titles, examples, patterns, etc.) are untrusted input that may contain */ sequences. When these values are embedded into JSDoc block comments in generated TypeScript output, a */ sequence prematurely closes the comment block, producing syntactically invalid TypeScript. This affects any spec with response types or schema annotations containing */.

Solution

Add a centralized escapeJSDocContent() method to SchemaFormatters that replaces */ with *\/ in any value destined for JSDoc output. The method handles undefined (returns "") and coerces non-string values via String(), since OpenAPI fields like minimum, maximum, and default can be numbers, booleans, or objects.

The escape is applied consistently across all JSDoc-emitting code paths:

• schema-formatters.ts — escapeJSDocContent() is called within formatDescription() and on enum field descriptions during formatting
• code-gen-process.ts — escapeJSDocContent is exposed as a template utility alongside formatDescription
• data-contract-jsdoc.ejs — All @format, @min, @max, @pattern, @example, @default, and other annotation values are escaped; title is routed through formatDescription for consistency
• object-field-jsdoc.ejs — Same treatment for object field annotations
• route-docs.ejs — Route documentation tags, response status codes, type signatures, and descriptions are escaped
• api.ejs — Top-level API metadata (@title, @version, @license, @baseUrl, @contact, etc.) is escaped

A dedicated test suite (tests/spec/issue-1321/) validates that */ in descriptions, enum values, examples, and patterns produces valid output.

Verification

• bun run test passes, including snapshot updates for tests/spec/responses/ (the existing inline response type comments now use *\/ instead of the previous ad-hoc \* / *\ escaping)
• New test in tests/spec/issue-1321/ covers a schema with */ in descriptions, enum descriptions, examples, and patterns

Closes #1321
Closes #672
Closes #704
Supersedes #1368

---

Note

Medium Risk
Touches core code generation formatting/templates, which can subtly change emitted TypeScript comments and snapshot outputs across many users, though the change is narrowly scoped to JSDoc escaping.

Overview
Prevents JSDoc comment injection/broken generated TypeScript by escaping */ sequences coming from untrusted OpenAPI fields.

Adds SchemaFormatters.escapeJSDocContent() and wires it through the codegen/template utilities, then updates all JSDoc-emitting templates (schema/field docs, route docs, and top-level API metadata, plus enum value descriptions) to consistently escape annotation values (e.g., @example, @pattern, response types/status, tags, routes).

Adds a new regression spec (tests/spec/issue-1321) with snapshots and updates existing response snapshots to reflect the new escaping behavior.

^{Written by Cursor Bugbot for commit 7f25d28. This will update automatically on new commits. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7f25d28

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
swagger-typescript-api	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR