Skip to content

Conversation

kristianjf
Copy link
Contributor

Changes

Adds a new transformProperty hook that allows users to modify individual property signatures within Schema Objects. This enables adding JSDoc validation annotations and other property-level modifications that can't be achieved with existing transform/postTransform hooks.

Related Issue: Resolves #2448

Features Added:

  • New transformProperty option in OpenAPITSOptions
  • Hook integration in schema-object transformer
  • Comprehensive documentation with JSDoc validation examples
  • Test coverage for JSDoc annotations and edge cases

How to Review

  1. Core Implementation: Review src/transform/schema-object.ts for hook integration
  2. Type Definitions: Check src/types.ts for the new interface
  3. Documentation: Review docs/node.md for examples and explanations
  4. Tests: Run pnpm test to verify new test cases pass

Key files to focus on:

  • src/transform/schema-object.ts - Main implementation
  • docs/node.md - Documentation with examples
  • test/node-api.test.ts - Test coverage

Checklist

  • Unit tests updated
  • docs/ updated (if necessary)
  • pnpm run update:examples run (only applicable for openapi-typescript)

Kristian Francisco added 2 commits September 16, 2025 07:24
…nature modification

Adds a new transformProperty hook that allows users to modify individual property signatures within Schema Objects. This enables adding JSDoc validation annotations and other property-level modifications that can't be achieved with existing transform/postTransform hooks.

Features:
- New transformProperty option in OpenAPITSOptions
- Hook integration in schema-object transformer
- Comprehensive documentation with JSDoc validation examples
- Test coverage for JSDoc annotations and edge cases

Resolves openapi-ts#2448
@kristianjf kristianjf requested a review from a team as a code owner September 16, 2025 14:37
Copy link

netlify bot commented Sep 16, 2025

Deploy Preview for openapi-ts failed.

Name Link
🔨 Latest commit
🔍 Latest deploy log https://app.netlify.com/projects/openapi-ts/deploys/68ee6ed960e829612c799d7c

Copy link

changeset-bot bot commented Sep 16, 2025

🦋 Changeset detected

Latest commit: fcd7122

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

This PR includes changesets to release 2 packages
Name Type
openapi-typescript Minor
swr-openapi Major

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

- Format transformProperty type definition for better readability
- Apply biome formatting to feature-related test code
- Keep changes focused only on transformProperty feature files
@sahand-sn
Copy link

any idea when this might merge?

@kristianjf
Copy link
Contributor Author

Hey @htunnicliff @gzm0 @kerwanp — would you have a moment to review PR #2449? It adds a small transformProperty hook for property-level customization (non-breaking). Drew was supportive of the direction in the discussion but has been busy. Happy to rebase/split/edit to make this easy to merge. Thanks!

Copy link
Contributor

@drwpow drwpow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great! Thank you for proposing, investigating, and implementing everything (and for your patience)! Will ship this out later today


// Apply transformProperty hook if available
if (typeof options.ctx.transformProperty === "function") {
const result = options.ctx.transformProperty(property, v as SchemaObject, {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. This is what we do in a lot of other places, too—don’t just test the presence of the hook, but also test if it returns something. A consumer may pass this, but still return undefined or null when they want to skip the transformation.

export type $defs = Record<string, never>;
export type operations = Record<string, never>;`,
options: {
transformProperty(property, schemaObject, _options) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great not only as a test, but many users rely on tests to see examples of usage. Especially working with TypeScript’s comment API which can be unwieldy, users will get a lot of mileage out of this ❤️

@drwpow
Copy link
Contributor

drwpow commented Oct 14, 2025

Note: failed Netlify deploy is unrelated; we had a problem with Netlify on the HEAD commit for this that’s since been fixed.

@drwpow drwpow merged commit bdd5ddb into openapi-ts:main Oct 14, 2025
7 of 11 checks passed
This was referenced Oct 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

openapi-ts Relevant to the openapi-typescript library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

4 participants