Hacker News Reader

Comment by GOATS- | Hacker News Reader

I find it odd that you've struggled so much with generating API clients. I've generated C# and TypeScript (Angular's HttpClient and React Query) clients for my API and never had any issues with them. With that being said, I didn't use OpenAPI's Java-based code generators and rather used ones made by third-party developers such as NSwag[0] and openapi-codegen[1].

[0]: https://github.com/RicoSuter/NSwag

[1]: https://github.com/fabien0102/openapi-codegen

View on HN

You said it yourself — the “official” generator is awful and very hard to modify or extend (well, you didn’t say that, but I’m saying it) and while there are many alternatives, they’re not always easy to find. I had some success with swagger-typescript-api[1], but eventually got tired of it and wrote my own generator. Despite looking around quite a bit at what’s available, I never heard of openapi-codegen, which looks quite good.

I think it’s a pretty big problem for many devs that so many of the options are mediocre and they’re quite difficult to evaluate unless you have a lot of experience, and even then it takes a lot of time.

[1]: https://github.com/acacode/swagger-typescript-api

Technically, there isn't an "official" OpenAPI 3.x tool of any sort. SmartBear/Swagger is no more official than any other vendor with 3.0+ (obviously it's different for the versions named "Swagger"!). I am working on an official parser/linter (oascomply) on a contract for the OpenAPI Initiative to set a baseline to help tool developers implement consistent support for the spec. However, this is more about the parts of OAS outside of the Schema Object.

Nswag leaves much to be desired. I deployed an OpenAPI server and the initial deployment partners using nswag begged us to change the API to suit an issue that was reported and nswag hadn't fixed in years. I respectfully told them to pound sand and deal with it manually or better yet be a good citizen on the ecosystem that they are using for free and contribute a patch. Last I checked they were still manually patching their codegen on each deploy. /Shrug

Nswag has important issues that are many years old still in their backlog.

1.6k issues, oldest unresolved 7 years old:

https://github.com/RicoSuter/NSwag/issues?q=is%3Aissue+is%3A...

I've been using redux toolkit's OpenAPI code generator for a side project and it's been pretty good. The documentation is a bit lacking and it could certainly use more work to make names more customizable. The generated code comes out looking very much machine generated. But I love that RTKQuery (redux toolkit query) has client side caching so that if I use a query param that was already used before, it will remember and just serve from the local cache.

But it's been nice being able to make a backend change, run the code generator, and then be able to use whatever API in react. I hope this type of stuff gets developed more!

[0] - https://github.com/reduxjs/redux-toolkit/tree/master/package...

I've had the same experience and gripes as the comment op, but RTKquery is one of the better experiences I've had with OpenApi based tooling.

But ya... JSONschema is confusing and doesn't really support type composition the way you think it would.

If your API model is simple, then you'll probably have decent experience with clients... But if you need "allOf/anyOf/oneOf" and to restrict "additionalProps", you're probably going to have a rough time...

Yup. JSON Schema is a constraint system, not a data definition system. https://modern-json-schema.com/json-schema-is-a-constraint-s...

This. I've found you can get a long way with NSwag, and the barrier to entry is low. I've got a post that walks through how to get a TypeScript and a C# client generated.

https://johnnyreilly.com/generate-typescript-and-csharp-clie...

Reply on news.ycombinator.com