OpenAPI Generator allows generation of API client libraries from OpenAPI Specs

>OpenAPI Generator allows generation of API client libraries from OpenAPI Specs

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 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 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 in the generated code 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 function result.

And as I wrote in the "sans-io" section of that README, I also believe the generator's approach of providing an API client that has all decisions made for you, like whether the API is sync or async (in languages where that matters), what HTTP library it uses internally, etc is overly limiting. It means that a user who does not agree with even one of those decisions is prevented from using the entire generated library. In my opinion the part where models/requests can be encoded to bytes and models/responses can be decoded from bytes is separate from the part where bytes are sent and received over HTTP, which is why k8s-openapi only does the former and you can write a thin wrapper to use it with your chosen HTTP client.

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 a) you should have a plan for bugs in the spec and bugs in the generated code, b) you should have a plan for generating your own bindings instead of using a third-party library that generated them for you if you don't agree with any of the third party's choice of codegen parameters, and c) you might find hand-written bindings, or a bespoke hand-written generator for that particular spec, worth the investment.

I talked to a startup ( https://stainlessapi.com/ ) about a service they provide where they take an OpenAPI spec and build good SDKs on top of it. This included making sure they are idiomatic, included examples, handled exceptions (Edit: like if one SDK consumer needs a slightly different thing because they use a different, custom API, not like network or language exceptions) if needed, and some other goodness. I passed for now because they don't have the language support we need and I am not sure if we need their level of sophistication, but others may benefit from talking to them. (I think the founder helped build Stripe's API docs, IIRC.)

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!

I prefer graphql because of this.

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 you 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.

Or for that matter Sun (now ONC) RPC, CORBA, DCOM, DCE, gRPC, or XPCOM?

I'm also curious about the reverse direction -- can I generate an openAPI spec from my typescript Api? I'd rather write code than schemas.