feat: OpenAPI generator for frontend

[Tymek]

Inconsistencies that we get by writing API integration by hand:

• A lot of duplicated code
• We had bugs where for example HTTP method didn't match
• It's not clear how to handle errors
• Cache invalidation on different levels of abstraction

Things to take into consideration

• Possible errors in parsing data are a big concern
  • If generated code is trying to be smart and parse JSON and Date, this can cause serious bugs.
• To test: Can we generate types out of OpenAPI anyOf & oneOf?
• We would like to avoid lock-in with the library that we end up using.
  • We need to be able to compose functionality on top of it, for example with custom fetcher.
  • Something like "middleware" is the pattern we are looking for. Example use is conditionally fetching from an endpoint.
• Right now to generate types we need to run Enterprise to get OpenAPI, and we generate frontend
  • It's hard to synchronize changes
  • We can crate a separate package for entire schema

Possible solutions

Dependencies that we can use (click to expand)

• @openapitools/openapi-generator
  • https://github.com/OpenAPITools/openapi-generator
  • It's what we currently have
  • Generates fetch API
  • Doesn't have React hooks generator
• orval
  • https://github.com/anymaniax/orval
  • Can generate SWR or React-Query hooks
  • Unfortunately it is using axios
    • Shouldn't be hard to modify for fetch or got
    • https://github.com/anymaniax/orval/blob/master/packages/swr/src/index.ts
• rapini
  • https://github.com/rametta/rapini
  • More opinionated
  • Also with axios
• @openapi-codegen
  • React-Query+fetch
  • https://xata.io/blog/openapi-typesafe-react-query-hooks

[simenandre]

Why not try GraphQL?

[Tymek]

Because it's a huge rewrite with no clear benefits, if it's done for both frontend and backend, or a level of not useful wrapper if we use it only on frontend. You're welcome to state your arguments and/or provide a POC.

[simenandre]

In my personal experience I find that OpenAPI doesn't have that great tools for generating clients, and I think this mainly comes down to people misunderstanding the OpenAPI specification (or not caring enough, maybe).

AFAIK, GraphQL has better tooling at this point, not to mention better documentation. Another option might be to look at tRPC? The benefits for both options are end-to-end type-safe APIs.

I appreciate that it's a large rewrite to change the transport layer, and it might not be worth it for what this issue wants to achieve. However, there are clear benefits with GraphQL, might not make sense right now.

I'll leave you with that 👍 Let me know I can help!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.