docs: OpenAPI does not differentiate between public and private endpoints

[milanjaros]

It is hard for beginner API consumers to differentiate between public and private endpoints.
The documentation describes REST API Public and Private Endpoints pretty well.

There is a Private security scheme defined and applied to all endpoints in linked OpenAPI (Swagger), but not Public ones.

To achieve that (in OpenAPI), there is needed to define both schemes:

components:
  securitySchemes:
    Private:
      type: apiKey
      in: header
      name: Authorization
      description: "Every time you create a new Project Environment, an environment API key is automatically generated for you. This is all you need to pass in to get access to Flags etc. <br />
        Example value: <br />
          Token 884b1b4c6b4ddd112e7a0a139f09eb85e8c254ff"
    Public:
      type: apiKey
      in: header
      name: X-Environment-Key
      description: "Things like creating new flags, environments, toggle flags or indeed anything that is possible from the administrative front end. <br />
        Example value: <br />
          FFnVjhp7xvkT5oTLq4q788"

Then apply default (Private) security to all endpoints:

security:
  - Private: []

Ten apply the Public scheme to appropriate endpoints:

paths:
  /flags/:
    get:
      security:
       - Public: []

Unfortunately, I was not able to find the OpenAPI spec file, otherwise, I would send a PR.

[milanjaros]

See also OpenAPI spec: https://swagger.io/docs/specification/authentication/

[milanjaros]

I've realized that the OpenAPI is generated, so I just added the Public security definition to the SWAGGER_SETTINGS.SECURITY_DEFINITIONS.

[dabeeeenster]

Thanks @milanjaros - will look to get this merged in.