How to specify an endpoint's authorization is optional in openapi v3?

Question

I'm trying to document an existing API that contains various endpoints whose authentication is optional. That is, more data is returned if the user is authorized than if they were not authorized.

Could not find that explicitly in the OAspec v3. Is there a coding trick to define this situation?

My present work-around is to code for authorization, yet in a description of the endpoint write that authorization is optional. This works and seems adequate. Yet the purist in me wonders if there is another way.

Answer 1

To make security optional, add an empty requirement {} to the security array:

security:
  - {}   # <----
  - api_key: []

This means the endpoint can be called with or without security.

Source: this comment in the OpenAPI Spec repository.