openapi-code-generator VS openapi-typescript

Whilst it's not as expressive/flexible as typespec, and in my experience it's not always well supported by tooling, you can do $ref's across files in openapi specifications.

Eg: https://github.com/mnahkies/openapi-code-generator/blob/main...

I've become interested in SBOM recently, and found there were great tools like https://dependencytrack.org/ for CycloneDX SBOMs, but all I have is SPDX SBOMs generated by GitHub.

I decided to have a go at writing my own dependency track esque tool aiming to integrate with the APIs GitHub provides.

It's pretty limited in functionality so far, but can give a high level summary of the types of licenses your repository dependencies use, and let you drill down into potentially problematic ones.

Written in NextJS + mui + sqlite, and using another project of mine to generate most of the API boilerplate/glue (https://github.com/mnahkies/openapi-code-generator)

Congratulations on launching, you have some interesting ideas in there.

Using a LLM to generate missing operation ids isn't something I've tried, instead I simply combine http method plus path segments which at least guarantees uniqueness [1]. I do a similar thing for extracting and naming inline schemas based on the operation and media types [2].

How do you prevent naming collisions? And do you find the resulting names to be significantly better than a deterministic approached like I described?

I'll definitely checkout the curated specifications - always useful to get more high quality (and hopefully varied) specifications to test my code generator with, and the lint rules is a great idea - I've had to explain what patterns lend themselves well to code generation many times.

I'm on mobile so may have missed it, but looking at one of your typescript examples I couldn't see any runtime response body validation, is this something you're thinking about?

- [1] https://github.com/mnahkies/openapi-code-generator/blob/main...

Yeah I'm also on the schema first side of the debate.

I think for me it comes down to a few key points:

- APIs are forever, the choice of language/framework is an implementation detail

- Constraining yourself to what can be represented in the specification is better than generating a specification from implementation that may not be capable of expressing the full details

- When working with diverse languages it provides a common ground/language for discussing API changes. Eg: if you have java backend, kotlin android, swift iOS, react/whatever web you can bring everyone together with the spec

- Subjective, but a good spec will include a bunch of documentation and examples that tend to create a lot of noise in the code. I personally prefer to keep this in the spec and the implementation smaller

I think the main counterpoint to this is that you can generate the spec and then take that and change your mind if you later change language/framework etc - it's not a one-way door.

My biggest bug bear is that regardless of spec first or implementation first, you should have something you write once and generate the rest of the glue from (eg: docs, client sdks). Writing each piece manually/independently always leads to drift and bugs.

(I'm working on my own little openapi -> typescript code generator over here https://github.com/mnahkies/openapi-code-generator - eventually plan to support more than typescript, and adding typespec support is something I'm currently considering)

OpenAPI TypeScript

I'll preface all of this with a couple esoteric design goals that I had in mind:

1. I actually _want_ an SPA. You might not need an SPA, if you don't need one then Vue/React/etc are overkill, etc.

2. I want to power as much of the SPA as I can using the same REST API as my core product, both for dogfooding reasons and for consolidation. Many people might argue that this is a bad idea.

---

With that in mind, some specific packages that I highly recommend:

1. Django-vite (https://github.com/MrBin99/django-vite). This makes it very easy to serve an SPA from the actual django response/request model

2. Some sort of way to get type information (if you're using TypeScript) into the frontend. I use a frankensteined system of the OpenAPI spec that django-ninja generates + openapi-typescript (https://github.com/drwpow/openapi-typescript). This means when I add, say, a new field to a response in Django, I immediately get typechecking for it in Vue — which has been _tremendously_ useful.

3. Django-typescript-routes (a package I extracted and open-sourced!: https://github.com/buttondown-email/django-typescript-routes) which gives your front-end routing information based on the Django router.

Glad to see alternatives but disappointed that Bruno does not support OpenAPI specification.

At my company, we hand-edit OpenAPI specs in YAML and it gets consumed by many tools that generate types[0], static analysis and dynamic checks[1]. The OpenAPI spec itself is linted[2]. And of course, Postman consumes OpenAPI.

Tools that are built on open standards will naturally see greater adoption over those that use proprietary formats.

[0]: https://openapi-ts.pages.dev

Another great library to generate TS types from OpenAPI is https://github.com/drwpow/openapi-typescript . It provides the types as single objects you access via indexing, which is pretty nice. There's a partner library to generate a typed fetch client.

If you're willing to document your API with an OpenAPI schema, then it should be possible to generate TypeScript types based on the OpenAPI schema with something like openapi-typescript. Also, Typebox can generate JSON schemas, maybe it can be used to generate something that the front-end can also use?

REST

In this sample, we'll achive it using openapi-typescript and openapi-typescript-fetch.