Render API docs

[SchrodingersGat]

Render API schema as part of documentation.

• A snapshot of each schema will be available at each release, and also for "latest" (master)
• API schema file available for download (.yaml file)

References

• Generate API docs #6319
• [FR]Add servers section to the OpenAPI schema #6350
• [FR] API schema tracking in QC #6269

[netlify]

✅ Deploy Preview for inventree-web-pui-preview canceled.

Name	Link
🔨 Latest commit	c9ebdbd
🔍 Latest deploy log	https://app.netlify.com/sites/inventree-web-pui-preview/deploys/65e26b4d62d07a0008f0f0f2

[matmair]

Seems reasonable. Is the api supposed to be rendered already?

[SchrodingersGat]

Seems reasonable. Is the api supposed to be rendered already?

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

[martonmiklos]

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!

[wolflu05]

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.

[matmair]

The stuff needed for that is in #6440

[SchrodingersGat]

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 :)

[matmair]

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.

[SchrodingersGat]

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

[SchrodingersGat]

The generated schema file (.html) is 16MB - which might take some time to load. Do we think this is an issue?

[wolflu05]

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.

[SchrodingersGat]

@wolflu05 nice idea - any idea how to achieve that?

[wolflu05]

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.

[SchrodingersGat]

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...

[wolflu05]

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.

[matmair]

@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

[SchrodingersGat]

@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

@matmair why is the CI passing then - the API schema errors should cause CI to fail...

[SchrodingersGat]

@wolflu05 I have split machines out into their own path now

[wolflu05]

Thank you.

This error is interesting, because there is actually a correct schema annotation with extend_schema.

[matmair]

@SchrodingersGat as far as I can read the CI runs the API schema task failed and threw an error

[wolflu05]

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?

[matmair]

It fails within the CI job, I think that is enough

[wolflu05]

I see, but why does the ci does not fail on master then? The machine api is already merged in there.

[SchrodingersGat]

@matmair @wolflu05 any ideas how we should proceed here? This is the final blocker for the 0.14.0 release

[matmair]

AFAIK there is a schema issue and a problem with translations; I have just restarted the docs CI - maybe it runs now

[SchrodingersGat]

@matmair any chance you can have a look at this? I am still a bit confused by the CI process here

[wolflu05]

@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 schema.yml file is not created, so a later step expecting this file failed because it cannot find it.

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.