search

openapi-ts / openapi-typescript

Generate TypeScript types from OpenAPI 3 specs
https://openapi-ts.dev
MIT License
5.22k stars 419 forks source link

Only generate models and export at root level #1506

Open alessiomatricardi opened 6 months ago

alessiomatricardi commented 6 months ago

Description

As for now, this tool "translate" the OpenAPI specification and export everything inside a single file. If the YAML/JSON specification is big enough (eg. we have a microservice which its JSON spec is ~ 2MB) and you need only to obtain the models from, the information overflow is not trascurable.

Proposal

My proposal is to define an option (eg --only-schemas) which export only the component schemas and export them at root level as done in #1260 export type PersonModel = { name: string; surname: string: }

What do you think about?

drwpow commented 6 months ago

Partial generation is possible, but tricky.

As I’ve commented in #1260, the proposal to have top-level “friendly names” doesn’t work for many schemas, because you’re allowed to use characters in component names that aren’t JS-safe. So we’d have to rename them somehow, while preventing conflicts.

Further, even having just --only-schemas is tricky, because we can’t just generate #/components/schemas; you’re allowed to use $defs (from JSONSchema), as well as refer to any other object in the document (even #/components/parameters and #/components/requestBodies). So it would actually be trickier having to trace everything, and make sure everything referenced gets loaded properly.

Trying to “tree-shake” an OpenAPI schema ultimately becomes a lot of brittle work for not much benefit. Our tests generate schemas that are several MBs in size in milliseconds, and consuming them in TypeScript is trivial on most machines. Further, you’re not meant to read the output directly; it’s supposed to happen via Intellisense and from reading your OpenAPI docs.

So all that said, I don’t think this is a feature I’d like to pursue. But for related things, such as improving Intellisence (#1462), or if there’s a performance issue, those are both great issues to tackle.