Closed senecolas closed 4 months ago
The latest updates on your projects. Learn more about Vercel for Git ↗︎
Name | Status | Preview | Comments | Updated (UTC) |
---|---|---|---|---|
openapi-zod-client | ✅ Ready (Inspect) | Visit Preview | 💬 Add feedback | Apr 13, 2024 9:12pm |
openapi-zod-client-rim4 | ✅ Ready (Inspect) | Visit Preview | 💬 Add feedback | Apr 13, 2024 9:12pm |
hey, that looks great ! I'm a bit reluctant to adding one more config option, as it's already pretty crowded in here and I don't have a lot of bandwidth to maintain these.. so, I have to ask: could this be done on your side if you had access to a simple callback ? like the endpointDefinitionRefiner
or a new one that would be called on each schema right before returning the result ? this way, I wouldnt have any maintenance cost, most of everyone specific needs would be taken care of in a future-proof way, including your use-case
Hey @astahmer,
I completely understand your approach and appreciate your concerns about maintaining a balance between feature richness and manageability. Taking your feedback into account, I'd like to propose the addition of a typescriptDefinitionRefiner
function.
Here's the proposed function signature:
/**
* A function to refine each Tanu type definition. Mostly useful for adding fields from SchemaObject
* that aren't defined yet in the default type definition.
*/
typescriptDefinitionRefiner?: (
defaultTs: ts.Node | TypeDefinitionObject | string,
schema: SchemaObject
) => ts.Node | TypeDefinitionObject | string;
We could call this function within the recursive getTypescriptFromOpenApi
before returning each Tanu type result, allowing for on-the-fly modifications to the type declaration.
Does this approach seem viable to you?
yes ! that would be perfect 🙏 thank you for understanding
I am particularly interested in this feature, as it would add a lot of value to this library. I'd prefer it over adding .describe
to the zod objects, which does not appear in Intellisense.
I totally understand your concerns about the core of the library supporting every use case and the maintenance burden that it imposes.
What would be the best way to share the solutions implemented in userland?
In response to the discussion and the need for a flexible solution, I've implemented the typescriptDefinitionRefiner function in a new PR, #278.
This approach allows for a highly customizable way to refine TypeScript definitions, including the ability to add JSDoc comments that are visible in IntelliSense, without the need to modify the core library further.
I propose to keep this PR (#275) open for the time being, as it may still offer value and insight into different ways users might extend the library's functionality in userland. This way, if there's interest in integrating the original --with-docs
config option directly into the library, we can revisit and assess based on community feedback and needs.
Looking forward to your thoughts and feedback on PR #278!
@eli0shin, Thank you for sharing your interest 🙏
@astahmer, unlike my previous PR (#282) that added an workaround option, I see this option as really valuable and I also have interest in this feature as it is. JSDoc is a highly valuable tool for development experience, and having an option that automatically adds that, without having to implement manually through a refiner, is an awesome feature for this lib.
I see the value in with-docs
, it's not something too specific so it makes sense to add it !
I still think https://github.com/astahmer/openapi-zod-client/pull/278 would be a great addition too, ideally both could be merged
I'd love to merge this PR as soon as a changeset
and some tests are added 🙏
I can do that if you don't have any spare time @senecolas
@dgadelha, thanks for your feedback ! Unfortunately, I'm too busy this week and the next one to carry out the tests myself . If you're available to do them, it would be great 🙏
Otherwise I'll take care of them at the end of my projects 😉
Alright! Do you mind adding me as a contributor on your fork?
@dgadelha, thanks, I've added you to the fork
PR updated :)
awesome ! thank you both for working on this 🙏
Add JSDoc Comments to Generated Types
Overview
This pull request introduces a new feature to the
openapi-zod-client
tool, enabling the automatic generation of JSDoc comments for the generated types. This feature leverages the various OpenAPI schema options to provide rich documentation directly in the generated code.Features
With the
--with-docs
flag, the tool now generates JSDoc comments that include:@description
).@example
) and multiple examples for better illustration.@deprecated
).@see
).@format
).minimum
(@minimum
),maximum
(@maximum
),minLength
(@minLength
),maxLength
(@maxLength
),pattern
(@pattern
), andenum
values (@enum
) for validation rules.This enhancement makes it easier for developers to understand the structure and purpose of the generated types without having to refer back to zod schemas or the OpenAPI documentation.
How to Use
To enable JSDoc comments in your generated types, simply include the
--with-docs
flag when running theopenapi-zod-client
command.Example:
Request for Comments
I welcome feedback on this feature, including suggestions for improvement or concerns about potential impacts. Please feel free to leave comments or questions in this pull request.
Thank you for considering this contribution to this project.