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.

Originally posted by @kristianjf in #2411