Deprecate security schemes

[miqui]

Although the OpenAPI specification supports multiple security schemas and associated schemes

• HTTP
• apiKey
• oauth2
• openIdConnect

Of this set http (for basic is most likely the most insecure. There is plenty of documentation concerning API security that suggests that a basic scheme is a bad idea. However, to facilitate the transition of an API that is using HTTP basic to a more secure scheme, I propose to add the deprecated attribute to the Security Scheme Object of the specification. Note, that there is some mention of deprecation in the 3.1 specification, but it seems to imply that deprecation is the responsibility of the scheme type (Oauth 2, implicit flow) owner.

Example:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      deprecated: true

The API's behavior could be reflected (i.e. signal to consumers) by using something similar to Deprecation HTTP header field draft for the deprecated scheme.
Note:

• deprecation could be reflected in the swagger-ui if http basic is used and flagged as deprecated.

General references

• IANA Authentication Scheme registry

[handrews]

@miqui I'm moving this over to a discussion in the "ideas" category because that's where folks are looking for ideas to review right now. We're only using issues for a few things in this repo that are short-term actionable.