As we head down our OpenAPI path (https://github.com/fusionauth/fusionauth-openapi has only been built for the last 9 months), I'm very interested in stories like yours. We're very interested in quality SDKs that are easy to update. But since we control the OpenAPI spec for the product, we might have an easier time than you in some ways.
Thanks for sharing!
It's a huge pain to maintain open API files and the generators are of varying quality supporting different specs. They also handle some parts differently in the output.
Which generator have used for typescript? There are 4 of them and all of them have different issues.
I find the axios one the most stable but keen to know.
How do you also handle refreshing token, incepting request while passing the client through configuration in these?
I find interception and changing response breaks some of the client methods without a way to handle the failure.
Any example or resources you found useful would be appreciated.
The same code you write to validate your request/response should automatically generate the OpenAPI see my comment here:
Many legacy codebase don't have an easy way to add schema and make code changes so you end up maintaining a separate file to avoid making changes in the codebase.
Or even better the opposite: I have a mini-framework [0] which does the validation and routing based on an OpenAPI spec, so the devs can focus on writing the business logic.
Edit: typo.
This is where a message centric approach can have advantages. Just generate the objects for the Request and Response DTOs (Data Transfer Objects), and let the developer interact with the API via whatever HTTP/GRPC/MQ client that is appropriate. You can externally provide a client that will use those DTOs directly for a good experience for those that prefer that, but in the end the DTOs are just the messages deserialized into the target language, which is useful in most languages/clients.
Having a complex tool to generate these clients from a complex spec is going to be fraught with issues IMO.
An alternate approach is get the web service API framework to generate just the message contracts in many languages directly. This enables very simple tools to pull down the generated code from a live/running API. We take this approach with the ServiceStack framework [0], and have found it provides a good developer experience. Also supports OpenAPI spec generation.
Each to their own, but I like this approach better than what feels like WSDL client generation all over again.
Ultimately built our own generator because we wanted to ensure specific behaviour for status codes in all of our clients.
We also published the generated clients as NuGet packages for our external consumers, the generated clients had the descriptions etc from the OpenAPI spec embedded in XMLDOC comments (C# code documentation) which helps developers a lot because it appears in IntelliSense in visual studio
I now maintain a separate copy of the templates that implemented some missing features of the spec that I needed, and adjusted access control etc to suit my needs. And I also feel like checking the generated code into source control is the way to go, if only for the build time improvements. I mean it doesn't change often enough to warrant being rebuilt all the time.
I once mad a stab at fixing it, but i got bored after getting feedback from my WIP PR that made it clear no one cared.
It does, but the generated code can be very shitty for some combinations of spec and output language. I maintain Rust bindings for the Kubernetes API server's API, and I chose to write my own code generator instead. The README at https://github.com/Arnavion/k8s-openapi has more details.
The point there about bugs in the spec is also not limited to Kubernetes. $dayjob's software product interacts with the Docker daemon's server API so we generated bindings using the Docker spec, but that spec also has had a bug where some timespan values used the wrong integer type ( https://github.com/moby/moby/issues/39131 ). Luckily we were able to fix them in our generated code because we'd opted to check the generated code in instead of building it dynamically at compile time. The generated code also had a bug in the function for pulling Docker images, because it did not account for the fact that pulling the image can fail at some point after it has started, in which case the HTTP response has a successful status code but the streaming body ends with an error record. We had to edit the generated code to incorporate any error records in the response body as an error in the overall request.
So basically, the generator exists and is a good starting point when you just want a quick and dirty way to consume an API, but you should always have a plan for bugs in the spec and bugs in the generated code, and depending on the spec you might find hand-written bindings worth the investment.