POC: Generating OpenAPI client

[winniehell]

This is a proof of concept for replacing the existing request logic in the frontend with a client implementation that is automatically generated from the OpenAPI specification. It is not meant to be merged but only serves to demonstrate the concept.

Advantages

• auto completion can be used for endpoints in the frontend
• static code analysis can find typos in request URLs
• typos in request parameters are prevented
• static code analysis can find endpoints that are still used in the frontend but removed / replaced in the backend
• naming consistency for endpoints is ensured between Python and JavaScript
• stubs / interfaces for complex response data

Disadvantages

• client code needs to added to the repository or always generated before starting the frontend
• new Python dependency
• manual modifications / overrides in the request logic is more difficult

[winniehell]

see c9e1aed

[winniehell]

this is the relevant improvement. when using TypeScript, there could even be validation for parameters and responses on the client side

[winniehell]

instead of using the backend port, a local file can be used

[ArneTR]

This PR feels a bit chaotic and I am trying to understand what the purpose is:

• Description missing
• Is it a generator for OpenAI? Or is the generator bash script just linked for compeleteness and was initally used?
• This seems like a lot of boilerplate just to query the simple API. Can it not be used with a classical external tool instead of carrying everything inside the repository?

[winniehell]

Description missing

sorry about that! it was not meant to be a standalone changeset but only an additional proof of concept to highlight what we had talked about. I've added a proper description now.

Is it a generator for OpenAI? Or is the generator bash script just linked for compeleteness and was initally used?

it uses a library (https://openapi-generator.tech/) to generate code from the specification provided by FastAPI. the bash script is just for documenting the command line flags that I have used. most of them could be added to a config file. whether or not to keep a script as a shortcut for the generator command is a matter of taste.

the command (or script) needs to be run whenever the backend API changes.

This seems like a lot of boilerplate just to query the simple API.

that is true and most of it is due to the fact that OpenAPI is strictly typed while JavaScript is not. there is much less boilerplate when using TypeScript (but that would be a separate discussion). some of the boilerplate can be avoided by fine tuning the config and there is also an open feature request to skip client side validation and rely on server side validation instead: OpenAPITools/openapi-generator#4168

Can it not be used with a classical external tool instead of carrying everything inside the repository?

I think I have answered most of the question above. whether to add the (redundant) client code to the repository or not is a highly subjective matter. personally I prefer to do so because then you can search in it or run git blame without navigating to the backend (essentially avoiding context switches).