feat: Add JSDoc comments to generated types with --with-docs option

[senecolas]

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:

• Descriptions from the OpenAPI schema (@description).
• Examples (@example) and multiple examples for better illustration.
• Deprecation notices to indicate obsolete fields or types (@deprecated).
• Links to external documentation for further reading (@see).
• Format specifications for data validation (@format).
• Constraints such as minimum (@minimum), maximum (@maximum), minLength (@minLength), maxLength (@maxLength), pattern (@pattern), and enum 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 the openapi-zod-client command.

Example:

openapi-zod-client generate --with-docs

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.

[vercel]

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

[astahmer]

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

[senecolas]

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?

[astahmer]

yes ! that would be perfect 🙏 thank you for understanding

[eli0shin]

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?

[senecolas]

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 🙏

[dgadelha]

@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.

[astahmer]

I see the value in with-docs, it's not something too specific so it makes sense to add it !
I still think #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 🙏

[dgadelha]

I can do that if you don't have any spare time @senecolas

[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 😉

[dgadelha]

Alright! Do you mind adding me as a contributor on your fork?

[senecolas]

@dgadelha, thanks, I've added you to the fork

[dgadelha]

PR updated :)

[astahmer]

awesome ! thank you both for working on this 🙏