Hi everyone,
I’m planning offer a workshop about OpenAPI at the Nextcloud Community Conference 2025.
Are there any specific topics you want to learn about or need help with?
Do you have an app where you want to add openapi-extractor support, but are stuck somewhere?
Are you going to migrate your frontend to Typescript and want to use the type definitions from the backend?
Is your native client using manually created data models and you want to level-up your type system and safety?
Please let me know if any of these are interesting to you and if you have other suggestions for the workshop, then I will consider integrating them.
See you at the conference!
That doesn’t seem to related to my workshop topic at all?
1 Like
sorry misunderstanding on my part
Hi @provokateurin,
As you know, i was partially involved into the ocs_api_viewer last implementation ;). Considering that, we used the OpenApi generator to build the openapi.json in our application (Workspace), for the incoming public OCS API.
What I can say is:
-
the openapi generator (by nextcloud) is very strict. And he fails and stop at the first error. So you can’t generate even a partial openapi.json, until everything is fine.
→ two improvements : be lazy as a generator, and explain what to do on error (with proposals)
-
It is a important work to fill it completely (ResponseDefinitions…). It requires a lot of time, and a lot of openapigeneration tries.
→ That part is documented, so that’s fine. Maybe complex data structures would be nice (list of detailed object…)
-
With OCS API, you need either to be authenticated, either by a user app password, either by bearer token. The first case is documented and easy to implement. For the bearer token, i didn’t find any sample nor use case. Maybe it is documented, but it is not easy to find. If it’s not, why not give some most used sso apps (user_oidc ?)
This is intentional, as there are many ways to build broken APIs and openapi-extractor tries to prevent everything that is absolutely broken and warns you about many things you might want to avoid when creating new APIs (but it still allows them in order to document existing APIs that are already used).
You must be using an old version of openapi-extractor. We already had an option --continue-on-error for a long time, but since a while this is the standard behavior and it logs all errors and only fails at the end. There also is --allow-missing-docs which allows you to get to a full spec quicker, but it will not force you to write the doc comments for all endpoints, parameters etc.
Yeah, there is no way around it really unfortunately.
Could you maybe open a PR for adding such an example? The reason most of these type examples are omitted because they are not openapi-extractor specific, but psalm/phpstan syntax, so I’d urge anyone to read those docs as well.
Those are either manually generated app passwords or created through the login flow (v2).
Thanks for your input, I hope I was already able to help you and I’m happy to talk to you again at the conference 