Experiment with other OpenAPI client generators

[david-crespo]

The official generator is doing really weird stuff with what seems like it should be a pretty standard AnyOf situation. So far we're hacking around it, but it's not sustainable.

It's time to trot out the alternative generators again and see how they fare.

• https://github.com/drwpow/openapi-typescript
• https://github.com/ferdikoomen/openapi-typescript-codegen
• https://loopback.io/doc/en/lb4/OpenAPI-generator.html (kind of dubious, seems like you might have to use loopback for your server?)
• https://github.com/acacode/swagger-typescript-api

Note that some generators, like the official one, generate request methods that wrap fetch for us. Others just generate all the types for the requests and responses, but wiring up fetches would be manual. This is not necessarily a dealbreaker — customizing fetch could potentially be a good thing (though it probably isn't) and there may be a way to add our own generation for the wrappers so that even though we're responsible for it, at least it's automatic.

[david-crespo]

Or... maybe we can forget all that and get Dropshot to give us a oneOf instead of an anyOf
oxidecomputer/dropshot#126 (comment)

[david-crespo]

🤷‍♂️ drpow/openapi-typescript

npx openapi-typescript app/docs/nexus-openapi.json --output schema.ts

Generates one schema file, doesn't generate fetches, but does have operations object with request params and expected responses. The generated schema is clean, problem is you still have to write the code that makes the requests and handle responses, etc. Seems like a pain, and nullifies a big part of the value of codegen.

💩 ferdikoomen/openapi-typescript-codegen

openapi -i app/docs/nexus-openapi.json -o ./gen-client/ --useOptions --exportSchemas true

Completely fucked on DiskState. Only ends up with one state in there, creating. Bizarrely, changing anyOf to oneOf has no effect.

👍 acacode/swagger-typescript-api

npx swagger-typescript-api -p ./app/docs/nexus-openapi.json -o ./gen-client --extract-request-params

Didn't actually run any requests, but this is a solid candidate. Handles anyOf almost tolerably and handles oneOf very cleanly:

export type DiskState =
  | { state: "creating" }
  | { state: "detached" }
  | { instance: string; state: "attaching" }
  | { instance: string; state: "attached" }
  | { instance: string; state: "detaching" }
  | { state: "destroyed" }
  | { state: "faulted" };

Testing the official generator with oneOf instead of anyOf

I was able to confirm that the official generator works way better with oneOf (see branch). That's probably the solution, or at least part of it. It still does weird stuff in code to parse to/from JSON, though. I think it's correct as JS, i.e., it produces the right value, but TS does not like it.

[david-crespo]

We did it folks. #535