search

astahmer / openapi-zod-client

Generate a zodios (typescript http client with zod validation) from an OpenAPI spec (json/yaml)
openapi-zod-client.vercel.app
717 stars 80 forks source link

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

Closed senecolas closed 4 months ago

senecolas commented 5 months ago

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:

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[bot] commented 5 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
astahmer commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

yes ! that would be perfect 🙏 thank you for understanding

eli0shin commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

@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 commented 4 months ago

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 🙏

dgadelha commented 4 months ago

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

senecolas commented 4 months ago

@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 commented 4 months ago

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

senecolas commented 4 months ago

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

dgadelha commented 4 months ago

PR updated :)

astahmer commented 4 months ago

awesome ! thank you both for working on this 🙏