Feature Request: Adding validation JSDoc annotations (@minLength, @pattern, etc.) to generated TypeScript properties

[kristianjf]

Background

We're using openapi-typescript to generate TypeScript types for use with tsoa (TypeScript OpenAPI) for API validation. We'd like to automatically generate JSDoc validation annotations above properties based on OpenAPI schema validation constraints.

Current Challenge

OpenAPI schemas with validation constraints like:

name:
  type: string
  minLength: 1
  pattern: "^[a-zA-Z0-9]+$"

Currently generate clean TypeScript:

interface MyType {
  name: string;
}

Using transform to add JSDoc results in inline comments:

interface MyType {
  name: /** @minLength 1 @pattern ^[a-zA-Z0-9]+$ */string;
}

But we need tsoa-compatible JSDoc annotations above properties:

interface MyType {
  /**
   * @minLength 1
   * @pattern ^[a-zA-Z0-9]+$
   */
  name: string;
}

Approaches Considered

1. Extending addJSDocComment function - Add validation constraints to the existing JSDoc generation
2. Adding transformProperty hook - Similar to transform/postTransform but exposes the property signature for modification
3. External post-processing - Parse generated types and add JSDoc via AST manipulation

Question

Is extending openapi-typescript's source code (option 1 or 2) the right approach for this use case, or would this be considered outside the tool's scope?

Both transform and postTransform only expose type nodes (resulting in inline JSDoc), but we need access to property signatures for above-property JSDoc placement. A transformProperty hook would provide this access.

Would the maintainers be open to a PR for either approach, or should we pursue external solutions?

Use Case

This would enable seamless integration between OpenAPI schemas and tsoa for runtime validation without manual JSDoc maintenance.

[drwpow]

This sounds great! The current JSDoc generated only provides minimal QoL, and currently doesn’t interop with any tools. So even minor breaking changes would be OK.

This is definitely within scope of this tool, and I think it’d be an important addition! We can also bake “generate tsoa-compatible JSDoc comments” into the core tests. I don’t anticipate there would be any breaking changes, but even if there were I think it would be worth it.

Thanks for suggesting! I made an issue to track this.

[kristianjf]

Quick update: the implementation is up in PR #2449. If anyone has bandwidth to review or try it out, feedback would be super helpful. Tagging @htunnicliff @gzm0 @kerwanp (and @duncanbeevers for visibility). Thanks all!