feat: add `input.patch.schemas` feature #2117

johnny-mh · 2025-06-01T12:40:51Z

Add new input.patch.schemas feature - Implement functionality to modify OpenAPI schema definitions during code generation process

bolt-new-by-stackblitz · 2025-06-01T12:40:54Z

Run & review this pull request in StackBlitz Codeflow.

changeset-bot · 2025-06-01T12:40:55Z

🦋 Changeset detected

Latest commit: a325600

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

This PR includes changesets to release 2 packages

Name	Type
@hey-api/openapi-ts	Patch
@docs/openapi-ts	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

vercel · 2025-06-01T12:40:55Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
hey-api-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 4, 2025 2:09pm

codecov · 2025-06-01T12:44:44Z

Codecov Report

Attention: Patch coverage is 81.08108% with 7 lines in your changes missing coverage. Please review.

Project coverage is 21.80%. Comparing base (870e035) to head (a325600).
Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/openapi-ts/src/createClient.ts	16.66%	5 Missing ⚠️
packages/openapi-ts/src/patchSchemas.ts	93.54%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2117      +/-   ##
==========================================
+ Coverage   21.67%   21.80%   +0.12%     
==========================================
  Files         268      269       +1     
  Lines       24666    24802     +136     
  Branches      837      859      +22     
==========================================
+ Hits         5347     5408      +61     
- Misses      19313    19388      +75     
  Partials        6        6

Flag	Coverage Δ
unittests	`21.80% <81.08%> (+0.12%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pkg-pr-new · 2025-06-01T13:03:10Z

Open in StackBlitz

@hey-api/client-axios

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-axios@2117

@hey-api/client-fetch

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-fetch@2117

@hey-api/client-next

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-next@2117

@hey-api/client-nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-nuxt@2117

@hey-api/nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/nuxt@2117

@hey-api/openapi-ts

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/openapi-ts@2117

@hey-api/vite-plugin

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/vite-plugin@2117

commit: a325600

mrlubos · 2025-06-01T13:20:50Z

Hey @johnny-mh, this is nice work! I sent you an email, would like to chat through this a bit

mrlubos · 2025-06-02T17:28:54Z

docs/openapi-ts/plugins/fix-schema.md

+  output: 'src/client',
+  plugins: [
+    {
+      name: 'fix-schema',


The main question I have for now is why did you decide to go with a separate plugin vs maybe making this an option in input? My understanding is you're manipulating the Hey API intermediate representation model in the plugin, whereas you could work directly with the OpenAPI spec in input

I understood that the Intermediate Representation serves as an interface to unify the differences between various OpenAPI versions.

Rather than having fix-schema plugin users write fix functions that need to be implemented differently for each OpenAPI version, I wanted them to be able to utilize a consistent interface.

However, if you're concerned about the Intermediate Representation being modified, I can refactor this to incorporate the functionality into config.input.fix as you mentioned.

What do you think?

Please let me know which approach you prefer, and I'll implement it that way

Nope, no need. I'm just curious about your thinking because I'll want to update the docs somewhat and understand this feature better. What you have works

mrlubos · 2025-06-02T17:30:48Z

packages/openapi-ts/package.json

    "commander": "13.0.0",
-    "handlebars": "4.7.8"
+    "handlebars": "4.7.8",
+    "immer": "10.1.1",


There's something not feeling right about adding 2 new dependencies for a plugin most people might never use. Are these dependencies crucial? Is there a way we could implement the needed functionality ourselves? How much effort would that involve?

The two packages are not crucial dependencies. I included them primarily to enhance the convenience of using this plugin.

If we change the implementation to only accept functions for spec modifications, we can eliminate the need for both packages entirely. We could then handle this by documenting guidance for users to incorporate these packages as needed when implementing their spec modification functions.

How would this affect developer experience? On the surface it sounds good to me, any reason we wouldn't want to do away with the dependencies?

I added the json-patch package to enable writing modification functions concisely. However, I think it would be fine to have users write their own functions or let them use whatever packages they need within those functions.

As for immer, I actually added it because I wasn't sure if directly modifying the Intermediate Representation would be okay. Now I'm thinking that if we're modifying within the input, it would similarly be unnecessary.

To conclude this thread, my preference would be to go dependency-free and let users bring their own if they need

mrlubos · 2025-06-02T17:32:18Z

packages/openapi-ts/src/plugins/fix-schema/config.ts

+  _dependencies: [],
+  _handler: handler,
+  _handlerLegacy: () => {},
+  name: 'fix-schema',


I'm assuming you built this because you have an actual use case. Is it a common use case for you? Or it happened only with one specification and you've decided to build this plugin?

I have collaborated with multiple backend developers who provide Swagger specifications. While some backend developers carefully write their Swagger documentation, in some organizations, they only write brief descriptions due to business schedule constraints, or sometimes provide them in completely incorrect formats.

Additionally, while some backend framework plugins for writing Swagger properly follow the OpenAPI specification, there are frameworks that fail to do so.

Whenever I encountered such situations, it was often difficult to communicate with backend developers and request modifications to the Swagger JSON. In these cases, this feature proved to be extremely useful.

For reference, this use case is included in the plugin usage guide that's part of the PR.

I actually didn't look at the implementation thoroughly. How do you ensure this plugin runs before everything else? Assuming that's what happens so other plugins work with the patched spec

That's why I added a note in the guide documentation to specify this plugin's order at the very front. But as you suggested, if we handle it directly in the input, we wouldn't need such precautions. I'll try implementing it that way.

Yeah I guess this feels more like a feature than plugin, so making it an option on input could be more intuitive. It really is something akin to the filters feature except you're patching the schema. I'm not against making it operate on the raw spec btw, that's what filters do as well. Presumably you know what the spec looks like if you're trying to modify it

mrlubos

It's starting to look pretty polished! Did you try this modified pull request in your repository? Still works okay?

mrlubos · 2025-06-03T20:47:37Z

packages/openapi-ts/src/types/config.d.ts

+      (
+        schema:
+          | OpenApiSchemaObject.V2_0_X
+          | OpenApiSchemaObject.V4_0_X


How is this not throwing anywhere 😳

Suggested change

| OpenApiSchemaObject.V4_0_X

| OpenApiSchemaObject.V3_0_X

Yeah, weird that it's not throwing! Fixed it anyway.

mrlubos · 2025-06-03T20:51:00Z

docs/openapi-ts/configuration.md

+export default {
+  input: {
+    fix: {
+      schema: {


Let's keep the naming consistent with OpenAPI?

Suggested change

schema: {

schemas: {

Sounds good, I'll fix that.

mrlubos · 2025-06-03T20:51:35Z

docs/openapi-ts/configuration.md

+```js [date-time to timestamp]
+export default {
+  input: {
+    fix: {


What do you think about calling this patch?

Suggested change

fix: {

patch: {

That sounds good to me. I'll make the changes.

mrlubos · 2025-06-03T20:52:36Z

packages/openapi-ts/src/fixSchema.ts

+  const schema = fix.schema;
+
+  const processSchemas = (schemas: Record<string, any>) => {
+    for (const key in schemas) {


It would be more efficient to loop through fix objects as they'll be always smaller (or equal) to schemas objects

That's a great point! Thanks for catching that.

mrlubos · 2025-06-03T20:53:26Z

packages/openapi-ts/src/types/config.d.ts

      include?: ReadonlyArray<string>;
    };
  };
+  fix?: {


Please add a JSDoc comment about this feature so people don't have to go to docs

I just added it. How does it look?

mrlubos

Looks good! Let's release it tomorrow. Thank you so much!

terijaki · 2025-06-05T08:40:56Z

@johnny-mh the types seems to be missing for the config?

mrlubos · 2025-06-05T09:18:37Z

@terijaki not released yet! #2117 (review)

terijaki · 2025-06-05T09:22:27Z

Oh my bad. It’s already in the docs and since I am on the latest 0.70.0 I thought I am good to go. 😊

Definitely looking forward to the feature!

mrlubos · 2025-06-05T09:34:26Z

Yeah, the docs pipeline should be improved at some point to prevent this. I'm always surprised when people find out so quickly, it's been only a few hours! Will push it later today!

mrlubos · 2025-06-05T10:15:27Z

@terijaki can't find your email from your profile so I'll say it here – thank you for sponsoring Hey API!

vercel bot deployed to Preview June 1, 2025 12:41 View deployment

johnny-mh force-pushed the add-fix-schema-plugin branch from a37d0f8 to f4d8e0a Compare June 1, 2025 12:59

vercel bot deployed to Preview June 1, 2025 13:00 View deployment

mrlubos reviewed Jun 2, 2025

View reviewed changes

johnny-mh force-pushed the add-fix-schema-plugin branch from f4d8e0a to 98eabb8 Compare June 3, 2025 17:48

johnny-mh changed the title ~~feat(fix-schema): add fix-schema plugin~~ feat(fix-schema): add input.fix.schema feature Jun 3, 2025

johnny-mh changed the title ~~feat(fix-schema): add input.fix.schema feature~~ feat: add input.fix.schema feature Jun 3, 2025

vercel bot deployed to Preview June 3, 2025 17:49 View deployment

johnny-mh added 3 commits June 4, 2025 02:54

feat: add input.fix.schema feature

69f7a2d

test: add input.fix.schema test

c72006e

docs: input.fix.schema

f4694a5

johnny-mh force-pushed the add-fix-schema-plugin branch from 98eabb8 to f4694a5 Compare June 3, 2025 17:54

vercel bot deployed to Preview June 3, 2025 17:55 View deployment

chore: adding changesets

a1435b9

vercel bot deployed to Preview June 3, 2025 18:04 View deployment

mrlubos requested changes Jun 3, 2025

View reviewed changes

vercel bot deployed to Preview June 4, 2025 14:04 View deployment

refactor: rename fix.schema to patch.schemas

a325600

johnny-mh force-pushed the add-fix-schema-plugin branch from 429c622 to a325600 Compare June 4, 2025 14:05

johnny-mh changed the title ~~feat: add input.fix.schema feature~~ feat: add input.patch.schemas feature Jun 4, 2025

vercel bot deployed to Preview June 4, 2025 14:09 View deployment

mrlubos approved these changes Jun 4, 2025

View reviewed changes

mrlubos merged commit 7a2905b into hey-api:main Jun 4, 2025
15 checks passed

github-actions bot mentioned this pull request Jun 4, 2025

Version Packages #2125

Merged

johnny-mh deleted the add-fix-schema-plugin branch June 5, 2025 11:47

Uh oh!

feat: add input.patch.schemas feature #2117

feat: add input.patch.schemas feature #2117

Uh oh!

Conversation

johnny-mh commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bolt-new-by-stackblitz bot commented Jun 1, 2025

Uh oh!

changeset-bot bot commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pkg-pr-new bot commented Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrlubos commented Jun 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

feat: add `input.patch.schemas` feature #2117

feat: add `input.patch.schemas` feature #2117

johnny-mh commented Jun 1, 2025 •

edited

Loading

changeset-bot bot commented Jun 1, 2025 •

edited

Loading

vercel bot commented Jun 1, 2025 •

edited

Loading

codecov bot commented Jun 1, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 1, 2025 •

edited

Loading