-
-
Notifications
You must be signed in to change notification settings - Fork 763
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[FR] API schema tracking in QC #6269
Comments
@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? |
@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. |
Check out #6463 - we can generate the API as part of the docs generation, and provide:
In this manner, we get versioned snapshots of the API for "free" without having to track another external repo - readthedocs does this for us |
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. |
We would release docs for every version release of InvenTree - i.e. |
So we are changing the API versioning system? Having (an unknown number of) missing schemas for versions will pose problems. |
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
The text was updated successfully, but these errors were encountered: