[FR] API schema tracking in QC

[matmair]

I would like to create a new org repo that holds all API schemas from now on and maybe a few versions back(starting from the point where it was possible to create OpenAPI schemas).
Additionally, I would like to add a CI check that generates the schema of the current PR and checks it against the latest one from the new repo to ensure API changes do not go unnoticed.
Thoughts? @inventree/triage

Originally posted by @matmair in #5861

[SchrodingersGat]

@matmair with reference to #6456

Would it be a better approach to encode the API schema into the documentation itself?

Your API change detection PR can be used to ensure that the API schema documentation is always up-to-date. We can potentially use something like this to generate docs pages from the schema file. Additionally the schema file can be made available for download.

This means that the "latest" API is always accessible on the docs site.

Then whenever we make a versioned release, that release has the pinned API docs available too.

If we can get this workflow up and running, is there an advantage to a separate repo where we track these API changes also?

[matmair]

@SchrodingersGat I think we should include as little generated content as possible in the source repo (inventree/inventree) to keep the git repo small/useable. The user can always create the schema purely from the source code using the schema command (that is reproducible).

Generating API docs is certainly something to shoot for but should take place in the build step. As a comparison: We also do not commit the HTML for the docs or the rendered language js files to the main repo.
A separate repo keeps the main history cleaner and leaves us more flexibility in regard to repo layout.

[SchrodingersGat]

Check out #6463 - we can generate the API as part of the docs generation, and provide:

• A documented schema in the docs
• A copy of the schema file for download

In this manner, we get versioned snapshots of the API for "free" without having to track another external repo - readthedocs does this for us

[matmair]

How do you reference specific API versions (for automatic client generation/backtesting between versions) with that? Are we releasing docs for every API version and does this mean we will have 2 different version numbers in releases? That does not seem easier than having another org repo similar to the Python client or app.

[SchrodingersGat]

We would release docs for every version release of InvenTree - i.e. 0.14.0, 0.14.1, 0.15.0 ... - and then also a version which is built for the master branch (which is latest on readthedocs).

[matmair]

So we are changing the API versioning system? Having (an unknown number of) missing schemas for versions will pose problems.