fix(OpenAPI): Fix array syntax ambiguities #13711
Conversation
Signed-off-by: provokateurin <[email protected]>
provokateurin
force-pushed
the
fix/openapi/array-syntax-ambiguities
branch
from
034f376
to
7ecf40c
Compare
| @@ -95,7 +95,7 @@ public function listBans(): DataResponse { | |||
| * Required capability: `ban-v1` | |||
| * | |||
| * @param int $banId ID of the ban to be removed | |||
| * @return DataResponse<Http::STATUS_OK, array<empty>, array{}> | |||
| * @return DataResponse<Http::STATUS_OK, list<empty>, array{}> | |||
There was a problem hiding this comment.
Really not a fan of this... it will never be a list. But we might introduce an 'error' key like we have on many other APIs, and then the response type changes from [] to {}
I guess it's hard to know which case is preferred technically.
There was a problem hiding this comment.
Yes, but even then this is a breaking change.
If you'd document it as \stdClass for now and later as array{error: string} it would be fine.
I don't think this change makes it worse as it is the same JSON data in the end.
There was a problem hiding this comment.
IMO the cleanest way is to have it return null as then you can later add any data and you are not limited to either objects or lists.
Unfortunately I don't think we can change this as it technically is a breaking change, though no client should really be looking at this data (and openapi-extractor also skips it automatically).
Same goes for the default value in the constructor of DataResponse which should be null as well.
There was a problem hiding this comment.
Yes, but even then this is a breaking change.
well form array<empty> to array{error? string} it should be okay?
But anyway, we will see.
There was a problem hiding this comment.
No, the former is [] in JSON and the later is {} or {"error": ""} in JSON and those are not compatible.
| @@ -120,7 +120,7 @@ protected function getBotFromHeaders(string $token, string $message): Bot { | |||
| * @param string $referenceId For the message to be able to later identify it again | |||
| * @param int $replyTo Parent id which this message is a reply to | |||
| * @param bool $silent If sent silent the chat message will not create any notifications | |||
| * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, array<empty>, array{}> | |||
| * @return DataResponse<Http::STATUS_CREATED|Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_REQUEST_ENTITY_TOO_LARGE, list<empty>, array{}> | |||
Fixes for nextcloud/openapi-extractor#168.
No real issues found, Talk code quality is great as always 🚀
🏁 Checklist
docs/has been updated or is not required