make it explicit that auth is optional

[wiese]

Auth was added in c077573. Most/All our endpoints are available without
authentication (but some records may be protected) - let's make it
explicit that unauthenticated use is legitimate.

As far as I can tell this has no impact in swagger ui, though.

See
OAI/OpenAPI-Specification#14

[itamargiv]

Looks fitting, But I'm not sure of the purpose of this then if it has no effect on the UI?

[wiese]

I'm not sure of the purpose of this then if it has no effect on the UI?

I'd think "spec first, UI second" - the specification should convey how our API ticks (can be read by humans, too). Would be great if the UI could fully show this as well but I hope we don't have to make this our construction site (now).

[itamargiv]

I'd think "spec first, UI second" - the specification should convey how our API ticks (can be read by humans, too).

Totally agreed, I don't think however it will be very clear to people that an empty object means optional auth without the context of the issue you linked here, therefore, I think we should add a note somewhere in the documentation that this is what it means.

[wiese]

I don't think however it will be very clear to people that an empty object means optional auth

I guess it would help if they read the specification.

Having looked at a couple of options of documenting this, I think it does not really fit anywhere and only a dedicated document would really make sense, yet would blow it out of proportion. Tried the general description for now.

[itamargiv]

Thank you! I think this is actually a fine place to document it.