-
-
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
Render API docs #6463
Render API docs #6463
Conversation
✅ Deploy Preview for inventree-web-pui-preview canceled.
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems reasonable. Is the api supposed to be rendered already?
Co-authored-by: Matthias Mair <code@mjmair.com>
Co-authored-by: Matthias Mair <code@mjmair.com>
- seems to render more reliably
It did not seem to be rendering reliably with that library. I have tried a new one - check it out now and see what you think |
InvenTree/InvenTree/settings.py
Outdated
} | ||
|
||
if SITE_URL: | ||
SPECTACULAR_SETTINGS['SERVERS'] = [SITE_URL] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The url subkey is missing here:
Optional list of servers.
# Each entry MUST contain "url", MAY contain "description", "variables" # e.g. [{'url': 'https://example.com/v1', 'description': 'Text'}, ...] 'SERVERS': [],
Apart from this it is working fine: I had been able to generate code with openapi-codegen without any hacking now!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe we can also use this then to auto generate a ts client (fully
Typesafe) for PUI (and also publish as npm package for the users) and a python client to eventually replace the InvenTree-Python package to reduce maintainance tasks there.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The stuff needed for that is in #6440
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The url subkey is missing here:
Optional list of servers.
# Each entry MUST contain "url", MAY contain "description", "variables" # e.g. [{'url': 'https://example.com/v1', 'description': 'Text'}, ...] 'SERVERS': [],
Apart from this it is working fine: I had been able to generate code with openapi-codegen without any hacking now!
Thanks, should be fixed now :)
docs/api.yml
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Having an auto-generated file here will create a lot of fun with merge conflicts and blow up the repo size, we have had this discussion multiple times in the last year with frontend resources and I pointed this out 2 days ago.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is only a WIP to ensure that we are all happy with the generated output. Once that is all clear, I'll setup a build pipeline to render this file on docs build, rather than actually committing the file itself
The generated schema file ( |
This is really laggy to open with a browser. How about splitting it in multiple pages categorized by the Django apps, so each apps api has a sub page. This reduces the download size and also the page size. |
@wolflu05 nice idea - any idea how to achieve that? |
Not really sure about how to support that, the mkdocs plugin seems like it's not. So we would need to either find a way to export the schema for each app individually or write a script to divide the schema into multiple pieces and then generate multiple pages that use the OAD plugin. |
Looking into this approach, doesn't seem too bad... |
Performance and load speed is much better now, thank you really much. Maybe it's worth putting the machine api endpoints into its own page, but I'm happy with it now. |
@wolflu05 seems like the machine API is throwing an error and not building https://github.com/inventree/InvenTree/actions/runs/7959068634/job/21725283385?pr=6463#step:4:40 |
- These will be auto-generated too
@matmair why is the CI passing then - the API schema errors should cause CI to fail... |
- Need git commit log to work
@wolflu05 I have split |
Thank you. This error is interesting, because there is actually a correct schema annotation with extend_schema. |
@SchrodingersGat as far as I can read the CI runs the API schema task failed and threw an error |
Yes, but not the generation step. That passed. The difference checking step is the step that failed. Has that something todo with the ongoing gh actions beta where there are bugs from time to time like this? |
It fails within the CI job, I think that is enough |
I see, but why does the ci does not fail on master then? The machine api is already merged in there. |
AFAIK there is a schema issue and a problem with translations; I have just restarted the docs CI - maybe it runs now |
@matmair any chance you can have a look at this? I am still a bit confused by the CI process here |
@SchrodingersGat The issue occurs while exporting the schema. A requests serializer is missing for introspection in one of the machine API serializers. However this doesn't throw an error, but instead the Regarding the machine api error it seems like this can be fixed with this patch: diff --git a/InvenTree/machine/api.py b/InvenTree/machine/api.py
index 9448d2ea9..2fec1b4cc 100644
--- a/InvenTree/machine/api.py
+++ b/InvenTree/machine/api.py
@@ -144,7 +144,7 @@ class MachineRestart(APIView):
permission_classes = [permissions.IsAuthenticated]
- @extend_schema(responses={200: MachineSerializers.MachineRestartSerializer()})
+ @extend_schema(request=None, responses={200: MachineSerializers.MachineRestartSerializer()})
def post(self, request, pk):
"""Restart machine by pk."""
machine = get_machine(pk) And to already fail in the export step, we may could check for the existence of the file and if not exit 1. |
Render API schema as part of documentation.
.yaml
file)References