mcp-openapi VS openapi-typescript

OpenAPI TypeScript is the closest thing I’ve found to perfection when your API is written in a different language than your client.

https://openapi-ts.dev/

openapi-ts/openapi-typescript is a powerful tool for generating TypeScript schema definitions from OpenAPI 3 specifications. The same organization also provides openapi-fetch, a type-safe fetch client library designed to work seamlessly with these generated schemas. Although very useful, one notable hurdle with openapi-fetch is that developers must manually implement client code for each API endpoint.

Overly expressive type systems have way more potential for footguns than simple type systems. In fact, I would say that overly expressive type systems make it easy to create unmaintainable code (still waiting on this showstopping bug which nobody can debug because it uses overly expressive types in TS: https://github.com/openapi-ts/openapi-typescript/issues/1769)

hi, few questions,

-who is your ideal user/customer? what stack are they using, and why do they use you?

-why did you decide to work on this? (ie, what inspired you?)

-how do you compare against openapi templated/generated SDKs? ie i use openapi-typescript (https://openapi-ts.dev/) and it is fantastic

-there seem to be some VC backed companies in the space: https://news.ycombinator.com/item?id=40147281, what is your edge?

-as someone who tried to maintain a few SDKs in my non-familiar languages (go, java, c#), i think i definitely see a paid use case for giving the problem to someone else who can maintain a quality SDK, but there are already 3-4 VC backed companies in the space, and i think the existing free tools are not bad if you spend some time with them, what is the gap/thing they're missing?

ty, john

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023, and in 2024 produce an openapi yaml or json file for that API with no other changes, is it somehow no longer a REST api? of course not. The article seems to be predicated on this distinction.

> The least-commonly used API model is REST

Is that true? I don't think it is frankly, though I suppose if any API that would be a REST api _if it didn't have an openapi spec_ is somehow no longer a REST api, then maybe? But as previously stated, I just don't think that's true.

> A signature characteristic of [REST APIs] is that clients do not construct URLs from other information

I don't think this is true in practice. Let us consider the case of a webapp that uses a REST api to fetch/mutate data. The client is a browser, and is almost certainly using javascript to make requests. Javascript doesn't just magically know how to access resources, your app code is written to construct urls (example: getting an ID from the url, and then constructing a new url using that extracted ID to make an api call to fetch that resource). In fact, the only situation where I think this description of how a REST api is used is _defensibly_ true (and this is hella weak), is where the REST api in question has provided an openapi spec, and from that spec, you've converted that into a client library (example: https://openapi-ts.dev). In such a situation, the client has a nice set of functions to call that abstract away the construction of the URL. But somewhere in the client, _urls are still being constructed_. And going back to my first complaint about this article, this contrived situation combines what the article states are two entirely distinct methods for designing apis (rest vs openapi).

Re: the article's description of rpc, I actually don't have any major complaints.

I've seen some truly insane TS types. Ones that validate SQL queries and stuff.

The problem with complex TS types is that there's no debug tooling. You can't set a breakpoint, you can't step through the type propagation. If there's an issue you have to just do trial and error, which can be extremely difficult if the type is super complex.

Here's a super complex type I ran into in the wild that has a bug that is extremely difficult to fix unless you burn hours on trial and error: https://github.com/openapi-ts/openapi-typescript/blob/main/p...

Related issue: https://github.com/openapi-ts/openapi-typescript/issues/1769...

> I must be a part of the problem because reading that type isn't too difficult. I also think types like this aren't innately problematic when they live in libraries.

Despite the star count on the repo, that particular type has a ton of bugs with it that are currently open issues, some of which are super esoteric to solve:

https://github.com/openapi-ts/openapi-typescript/issues/1778...

In this case ^ the problem was due to "behavioral differences based on the strictNullChecks ... compiler option. When that option is false (the default), undefined is considered to be a subtype of every other type except never"

Maybe I'm old school, but as long as we are using metaprogramming to solve a problem, I'd rather code gen dumb types vs. an ultra complex type that acheieves the same thing. Dumb types are easy to debug and you won't run into language corner cases like when `undefined extends` has different behavior when strict mode is on or off.

Tbh, there is no benefit of using this package if the API you are working with has an openapi spec, as there are other great libraries to help you generate accurate types such as https://github.com/openapi-ts/openapi-typescript. But I made this package to use when working with external apis that don't have an available spec.

Maybe I just have bad luck, but most of the libraries I've tried that are "crazy to look at" seem good in theory but are janky in practice. For example, openapi-fetch (https://github.com/openapi-ts/openapi-typescript/tree/main/p...), on paper seems great, but has lots of jank in practice.

And I would wager the bugs and jank are in no small part due to the extremely complex generics/constraints.