user_status: Add OpenAPI spec

[provokateurin]

Summary

From #36666. Adds the necessary annotations and descriptions.

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)

[provokateurin]

@nickvergessen I agree with your points, we could try to keep 100% compatibility but then we have a pretty bad API documentation (only because of the current API of course). The changes are only done to make the API more sensible and easier to use. I'm also pretty sure this breaking change might impact nothing because clients probably ignore the content already

[nickvergessen]

The changes are only done to make the API more sensible and easier to use. I'm also pretty sure this breaking change might impact nothing because clients probably ignore the content already

My point is more that this here is a sample. All kind of apps and app devs will adjust to this sample behaviour and break any of their APIs where they use [] as data (which is still the default)

[provokateurin]

So are you arguing for or against this breakage? I'm not really sure what you are telling me. As I said I can also remove the compatibility break, but then we stay with this ugly API. Maybe this should be discussed differently, because I only want to document the current state and not improve it (but it happened to me many times that I saw a bad API and tried to fix it)

[provokateurin]

Ok I will restore compatibility and type the value as array<empty> which is validated properly in psalm and is also useful in the spec.

[nickvergessen]

So are you arguing for or against this breakage?

I'm always against breaking APIs if it is not necessary.

As I said I can also remove the compatibility break, but then we stay with this ugly API.

¯\_(ツ)_/¯

Maybe this should be discussed differently, because I only want to document the current state and not improve it (but it happened to me many times that I saw a bad API and tried to fix it)

End of July?

Ok I will restore compatibility and type the value as array<empty> which is validated properly in psalm and is also useful in the spec.

Thanks, sounds good 👍🏼

[nickvergessen]

🤷🏼