Merged specifications are invalid

[MR4online]

Hi there,

I'm not sure, if this is the right place. Sorry, if not!

Problem:

Exporting the OpenApi definition from the new documentation here:
https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/

which downloads: https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.json

includes a lot of "Structural error"s.
Tested by importing it into swagger editor.

e.g.:
Structural error at paths./ocs/v2.php/core/getapppassword.get.responses.403.content.application/json.schema.properties.ocs.properties.data should be object Jump to line 3151

[joshtrichards]

Cc: @provokateurin

[provokateurin]

I'll have a look, but it's not necessarily wrong, because the swagger editor sometimes reports "errors" that are actually allowed by the spec.

[MR4online]

thanks a lot!
It's not only the swagger editor having problems reading the docs, but it's the most famous one.
(The errors prevent the code-generators I tried from building typescript and api classes correctly. with the same errors)

[provokateurin]

It's better to use the standalone specifications instead of the merged one.
In the meantime I noticed that the documentation repo uses a pretty old version of openapi-extractor and doesn't update it automatically.
I also confirmed the errors you were seeing and already know why they happen. I will now work on a fix for it, so the merged specifications will be valid.

[MR4online]

Thank you very much!
Could you please post some information on where to find the standalone versions? The merged one was the only one I found. 🙈 No rush on that.

[provokateurin]

You can usually find them in the root of the repositories that support them or in case of server they are at https://github.com/nextcloud/server/blob/master/core/openapi-full.json and https://github.com/nextcloud/server/blob/master/apps/provisioning_api/openapi-full.json for the respective apps.