openapi-typescript-helpers documentation

[thesammiller]

Per the openapi-typescript-helpers package README.MD:

This package isn’t as well-documented as the others, so it’s a bit “use at your own discretion.”

I am opening an issue to start a conversation about adding documentation. I would like to offer help in documenting as this package has recently helped me and the message about documentation gave me some pause as I reviewed it. While I'm not claiming to be an expert, I think some basic documentation could be added, but I am new to this project and welcome any direction.

I think import examples like in the openapi-typescript [README.md] (https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-typescript/README.md) and a code example like in the openapi-fetch [README.md] (https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/README.md) would be a reasonable starting place. If that sounds good I can try to put something together and submit a PR linking to this issue.

[drwpow]

Tagging @kerwanp who may have thoughts on this. My rough opinion is that all documentation is welcome, even for beta libraries. As long as it’s flagged appropriately with “beta” in the sidebar (Vitepress supports this and in titles I think), I’d be +1 for adding. But I know there’s already a PR to get this started: #2006

[kerwanp]

In my opinion, for openapi-typescript-helpers it would be overkilled to have a complete new section for just openapi-typescript-helpers which is a small types library mostly used internally or by projects that anyway requires a certain knowledge about Typescript types. Maybe a new page Helpers under the openapi-typescript could work.

This led me to a question. @drwpow is there a reason why the helpers are not part of the openapi-typescript package (under openapi-typescript/helpers)?

[drwpow]

This led me to a question. @drwpow is there a reason why the helpers are not part of the openapi-typescript package (under openapi-typescript/helpers)?

Yeah good question! 2 main reasons:

1. openapi-typescript-helpers came from openapi-fetch, not openapi-typescript
2. openapi-typescript-helpers are a dep of openapi-fetch. If they were moved into openapi-typescript then it would make that a dep of openapi-fetch, which has a lot of node_modules weight by comparison that openapi-fetch doesn’t need. Even though that doesn’t go to the client or anything, I still like to limit downloads and network transfer (both for consideration of end users but also being a generally good OSS citizen for npm etc)