How to document required privilege levels on endpoints?

[chrisinmtown]

Please tell me the recommended OpenAPI way of documenting endpoint privileges (such as roles) that are enforced by a back-end implementation. For example, an endpoint "GET /version" is open to every authenticated and authorized user, but an endpoint "POST /user" is only open to an authenticated and authorized user with additional privileges that are managed in the back end. This need doesn't seem to fit in the securitySchema feature. I have seen people mention "extensions" but I'm not sure which is right or where to find those extensions, and I definitely don't want to add items that might break the toolchain that generates (Python) clients and other features. Thanks in advance!

[handrews]

We now have a page on security on our learn site. If that doesn't address your question, I'd suggest opening an issue on the learn repo, as that is where we are documenting usage and best pratices that don't need to be in the spec itself.