Integrate OpenAPI client API generator

[Monstarrrr]

https://openapi-generator.tech/docs/installation

Also check this alternative https://wiremock.org/

[Monstarrrr]

Problem

Running the script

"api": "openapi-generator-cli generate -i http://localhost:8000/api/schema/redoc-ui/ -g typescript-node -o ./client-api"

using "@openapitools/openapi-generator-cli": "^2.13.4", gave the following error:
Error: 'java' is not recognized as an internal or external command, operable program or batch file.

Mention: https://github.com/OpenAPITools/openapi-generator-cli/issues/431#issuecomment-890711223

Solutions

• A. Install Java
  Less practical as it introduces an extra requirement for setting up and contributing to the project
• B. Use Docker
  Takes some time to setup initially, but we think we should use docker eventually anyways
• C. Use github action to generate the OpenAPI client whenever the API changes on the back-end
  Removes the need for having Java locally at all and automates the generation of the client api which may actually be what we want anyways

[Monstarrrr]

@seporterfield Thoughts on solution n°3 ?

[seporterfield]

Will going with the autogenerated client be a net benefit for the frontend?

If we do, option A is the only one that solves the problem of "I just made a small change to a Django ViewSet and now I need to pass different variables to axios on the same branch-- I need to regenerate the API client locally!"

Java would be a dev dependency, but at least it won't be an application dependency.

It's as easy as installing it once and forgetting about it.

[Monstarrrr]

Will going with the autogenerated client be a net benefit for the frontend?

Yes, mostly for having access to API types

If we do, option A is the only one that solves the problem of "I just made a small change to a Django ViewSet and now I need to pass different variables to axios on the same branch-- I need to regenerate the API client locally!"

Afaik anytime there will be any change in the API (Added/Edited/Removed endpoint), the client API will need to be regenerated.
I will just install Java and we'll see whenever we forget to regenerate and get issues as a result if it errors out right away and if the errors are explicit enough to quickly know we simply have to run the command. Because if that's the case then automating isn't needed.

[seporterfield]

Beyond just generating it locally, we should definitely check that it's been generated locally in a CI step.

[Monstarrrr]

Beyond just generating it locally, we should definitely check that it's been generated locally in a CI step.

Isn't that option n°3 ?

[seporterfield]

I interpreted your option 3 as automatically generating the client in CI and also committing it automatically.

If we instead generate the client in CI to simply check whether the correct API client has been generated locally before the author commits, we can enforce always having the correct API client by failing the flow if the author forgot to update the API client.

Like a pre-commit hook except in a CI step.

[Monstarrrr]

If we instead generate the client in CI to simply check whether the correct API client has been generated locally before the author commits [...] Like a pre-commit hook except in a CI step.

I don't know what is meant by "in CI" exactly. As in always generating it during a commit or something else, if something else then what trigger is it ?
I didn't think about generating it each time, but that could be an actual pre-commit. Downside is it'd generate every single time and slow us down a bit vs being able to auto-generate it when we detect a change in the API endpoints (may be too complex/time-consuming to implement tho).

[seporterfield]

"In CI" = In a continuous integration pipeline.

Concretely this would mean a GitHub workflow that will fail out whenever the API hasn't been correctly generated locally.

If it's fast enough we could try a pre-commit hook too. I doubt it, but if it's really fast then it can't hurt.

All pre-commits should also have CI checks, otherwise we could just push garbage/force future developers to have to use our pre-commit hooks and not use their own tools.

[seporterfield]

I don't know what is meant by "in CI" exactly. As in always generating it during a commit or something else, if something else then what trigger is it ?

Yes, a GitHub workflow triggered by a pull request/ commits to an open pull request.

I didn't think about generating it each time, but that could be an actual pre-commit. Downside is it'd generate every single time and slow us down a bit vs being able to auto-generate it when we detect a change in the API endpoints (may be too complex/time-consuming to implement tho).

I don't like the idea of a pre-commit hook for the API client for this very reason.

Generating the API client after making changes to the backend should be a step developers do locally before pushing, similar to running tests. Test suites get large, they do not belong in a pre-commit hook.

After pushing, a GitHub workflow will generate the API client and compare it to the one being pushed.

Not having generated the API client locally before testing and pushing can cause unforeseen discrepancies that just automatically generating the API client can never fix.

For example if the API client hasn't been generated locally before testing and pushing, the test suite could fail, but won't because the API client wasn't updated. This leads to errors/bugs that we would have otherwise detected if we generated the API client before running the tests.

We can avoid this by failing immediately and enforcing that developers check for any such discrepancies between frontend, API client, and backend, before they push.

[seporterfield]

150

[Monstarrrr]

Sounds good