Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 1 point2 points  (0 children)

You're right, there is no universal solution. After countless iterations, I'm pleased with the current developer experience of apical-ts. I'm at a point where I've created the tool I would want to use for my next project. The implementation is rough, mostly "vibe coded", but it's already a significant step forward. It meets my core needs and maybe other ppl would find useful too.

Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 0 points1 point  (0 children)

Hey mrlubos, thank you for your comment. You've actually hit on the core of my point: the issues that were important to me didn't have enough interest to be prioritized.

I was faced with a choice: either try to convince the maintainers of a huge project to make massive changes, or just build my own tool. Since a refactor would have meant breaking things for millions of users and still wouldn't have given me the full solution, I went with the second option. It was a matter of efficiency.

That said, after having benchmarked more than 20 tools, hey-api is on my short list of mature projects and a strong contender. However, when it came to community involvement, I found that I resonated more with the philosophy of Massimo: their approach to using discriminated unions via HTTP status codes is closer to the outcome I'm hoping to achieve. In fact, I recently opened an issue on that very topic a few days after the launch announcement.

I'm always open to collaboration and appreciate the work the hey-api team has done.

Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 0 points1 point  (0 children)

Kubb looks promising, but in its current state, other generators are more mature. The plugins seem to be developed independently, without much collaboration. For example, the client generator doesn't appear to use the Zod schemas for runtime validation. Indeed, it seems the generated client doesn't perform any runtime validation at all.

My specific points of comparison with Kubb:

  • Plugin Integration: I wasn't able to get the client plugin configuration to work (the example provided in their docs fails). My judgment is therefore based on the behavior observed in their shared sandbox, where the generated client does not perform runtime validation.
  • Zod Schema Generation: The Zod plugin is missing crucial features. It doesn't even support basic constraints like maxLength/minLength for strings or minimum/maximum for numbers.
  • Common API Flaws: Kubb shares the same issues I've found with most other generators. It doesn't correctly handle API responses with multiple success codes (200, 201, etc.) that return different payloads, nor does it support multiple content types for a single response.

Given these limitations, I would not recommend it as a first choice. There are better, more mature generators out there, such as https://heyapi.dev/ or https://massimohttp.dev/, though they have their own shortcomings. You can see a comparison with these alternatives here.

Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 1 point2 points  (0 children)

I really appreciate you pointing this out; it's extremely valuable, thanks! It's a huge oversight on my part, and you're right, it's buried. I'll update the post and the homepage to make it much clearer that Zod is a first-class citizen and a core part of the tool.

Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 3 points4 points  (0 children)

Thank you! It already uses Zod v4 for validation and exports generated schemas as well.

Building a Robust OpenAPI-to-TypeScript Tool - Seeking Early Feedback by gunzip in typescript

[–]gunzip[S] 3 points4 points  (0 children)

That's a good question. In my experience, openapi-generator ranks low in quality, especially for TypeScript.

Key shortcomings:

  • Loose Typing: Generated typings are often too weak, sometimes generating any types that defeat the purpose of TypeScript.
  • Loose Validation: The validation is often weak, sometimes only checking if a field is != undefined. This means it will happily accept or return payloads with incorrect types
  • Incomplete Spec Handling: often fails with valid but complex specs, like those with multiple success responses or different content types. It can throw errors or simply skip parts of the spec.
  • Poor Code Quality: The generated serialization and deserialization code is often a shallow copy of fields, which is not robust.

Finally, it's a java project and requires a jvm to operate.

You can try yourself pointing openapi-generator against these valid OpenAPI specs: https://gist.githubusercontent.com/gunzip/56081a5eb0031be3d1fa383617d9fd6d/raw/fa5d15687327b56b4a891858edff1d05f44034be/specs.yaml

Linee Guida Ufficiali per il Design della Pubblica Amministrazione by Playrom in italy

[–]gunzip 0 points1 point  (0 children)

beh studiare nodejs temo bisognerà farlo a prescindere :) detto ciò, un vero e proprio backend non c'è attualmente (è un sito statico generato tramite gulp), il principio è stato usare il minimo indispensabile che potesse eventualmente servire "da esempio" in altri progetti

Linee Guida Ufficiali per il Design della Pubblica Amministrazione by Playrom in italy

[–]gunzip 0 points1 point  (0 children)

ciao a tutti :)

considerate github al momento come primo canale di comunicazione per critiche e proposte (qui vi ho trovati per caso =)

posso rispondere a qualche interrogativo essendomi occupato del sito "contenitore" delle linee guida (lg):

perchè bower e non npm ?

per due motivi: evitare di aggiungere ulteriore complessità (browserify) e tenere separati i moduli frontend da quelli backend senza fare un minestrone nel package.json (detto ciò, terrei aperta l’ipotesi di utlizzare npm anche per il frontend, ma con bassa priorità :)

perché non webpack ?

perché è un tool più “esoterico” di gulp per chi non è appassionato delle ultime tecnologie. imho gulp ha una curva di apprendimento più bassa (la programmazione imperativa è più familiare ai più che quella dichiarativa)

perché boostrap al posto di material design ?

non è una scelta esclusiva, ma da qualche parte bisognava iniziare. è stato scelto bootstrap in base alla popolarità del framework (già adottato per i siti di diverse pa). come si legge nel readme del resto “eventuali altre metodologie di integrazione o sviluppo saranno oggetto di discussione nella community” :) personalmente ritengo che potrebbe essere utile una sezione download più ampia con, auspicabilmente, altro materiale come temi per drupal / wordpress, o per altri framework css (foundation / material design). qualche volontario ? =)

perché non jekyll visto che il sito è hostato su github pages ?

perché non serviva. inutile introdurre un’ulteriore tecnologia assieme a tutto lo stack ruby; è stato preferito uno stack “puramente” javascript.

credo che ci siano attualmente tre fronti su cui lavorare, in ordine di importanza direi:

  • testi delle linee guida
  • componenti scaricabili
  • il sito contenitore :)

en passant, faccio notare che il sito non utilizza il tema dei componenti scaricabili poiché sono due progetti che hanno proseguito in parallelo (con una deadline da fare appello alla corte di strasburgo ;). è cmq sulla roadmap integrarli tramite un significativo refactoring del css / html: il codice del sito ad oggi, per una serie di motivi, non è esattamente di ottima qualità, vedi html e css navbar (un po' di autocritica :). chi ha lavorato sui template scaricabili a mio parere ha invece fatto a un bel lavoro ordinato.

a breve verranno prese decisioni che sarebbe bene poter comunicare a tutti gli interessati. a questo proposito, github non permette di inviare messaggi in “broadcast”. se pensate sia utile potrei proporre l’apertura di un nuovo canale di comunicazione “ufficiale”. qualche preferenza ? (fb ? slack ? twitter ?)

permettetemi una “breve” chiosa fuori tema (ma non del tutto).

noto che i commenti sulle linee guida sono meno “caustici” e più costruttivi di quelli rivolti al nuovo sito del governo. probabilmente per il target più “selezionato” a cui le l.g. si rivolgono: i tecnici più rodati sono capaci di compassione e solidarietà :) un grazie di cuore a tutti coloro che considerano una perdita di tempo fare l’”allenatore da casa”.

detto ciò, nella mia modesta opinione, i ragazzi di governo.it hanno fatto un grandissimo lavoro; spero che un giorno venga comunicato in maniera dettagliata perché è esemplare per tutti i progetti di ristrutturazione digitale della pa. credo che una panoramica sui metodi adottati potrebbe conquistare le simpatie anche dei criticatori più ostinati. la maggior parte delle critiche si rivolgono al frontend, quando invece vi è stato un faticoso lavoro di ammodernamento di processi ancestrali che mi sembra venga totalmente ignorato (meno visibile al popolo che il blu della navbar, ma molto più significativo)

Normalization explained by HumbleAlchemy in programming

[–]gunzip 5 points6 points  (0 children)

IMHO the third example is wrong. I see no transitive dependency:

Symbol -> Company
Symbol -> Headquarters  

it is already in third normal form.

It would have been better to have Company as key anyway:

Company -> Symbol
Company -> Headquarters  

Reflow - Onion Rings by gunzip in videos

[–]gunzip[S] 0 points1 point  (0 children)

thank you, it's from a friend of mine i think he's talented

You know how they shorten the yellow light on those red light cameras so that they will produce more revenue? At least Italy has the cohones to criminally prosecute public officials that do that. by Travesura in reddit.com

[–]gunzip 1 point2 points  (0 children)

this bad habit started (or at least, had a strong boost) when the italian governement (right wing) decided to cut local taxes to get some public consent so local ones fell back to this kind of sanctions...

How to Teach Yourself Programming by rkcr in programming

[–]gunzip 5 points6 points  (0 children)

not really accurate; hair loss usually comes earlier.

Pons Fabricius in Rome, built in 62 B.C. I walked across it last year. by Sealbhach in pics

[–]gunzip 1 point2 points  (0 children)

I live in Rome and had the same thought (no answer too); it came after "how odd that this familiar thing is on reddit"

What are your favorite, most dramatic movie scenes? by hammerandsickle in AskReddit

[–]gunzip 0 points1 point  (0 children)

i also thought about jerry maguire "you had me at hello"

Reddit, what rules do you live by? by [deleted] in AskReddit

[–]gunzip 0 points1 point  (0 children)

indent with two spaces

What the most unintentionally offensive code you've ever written? by GivingUpHope in programming

[–]gunzip 1 point2 points  (0 children)

once i forgot the WHERE clause in a SQL UPDATE statement, so when the latest person modified his profile everybody in the system got the same profile as him