Refinement of security section using OpenAPI 3

[maxim-tschumak]

Please check if the PR zalando/restful-api-guidelines#551 introduces changes which are relevant to the Zally project.

[conorclifford]

The changes in the guidelines PR zalando/restful-api-guidelines#551 result in zally reporting broken APIs that I believe meet the new guideline rules.

A minimal example API that uses new guidelines that are not accepted is:

openapi: 3.0.1
info:
  title: testing123 API
  x-audience: company-internal
  x-api-id: deadbeef-cafe-babe-a91d-936bb408d996
  description: dummy api
  contact:
    name: bob
    email: bobbie@example.com
    url: https://example.com
  version: 0.0.0
paths:
  /greetings:
    get:
      summary: Return a greeting
      responses:
        default:
          description: some issue
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - BearerAuth:
            - simple.read
servers:
  - url: https://fake-name.zalandoapis.com
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Zally reports the following violations for the above:

The same minimal API with the old securityScheme setup does pass zally checks:

openapi: 3.0.1
info:
  title: testing123 API
  x-audience: company-internal
  x-api-id: deadbeef-cafe-babe-a91d-936bb408d996
  description: dummy api
  contact:
    name: bob
    email: bobbie@example.com
    url: https://example.com
  version: 0.0.0
paths:
  /greetings:
    get:
      summary: Return a greeting
      responses:
        default:
          description: some issue
          content:
            application/problem+json:
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - simple.read
servers:
  - url: https://fake-name.zalandoapis.com
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://token.example.com/oauth2/access_token'
          scopes:
            uid: Unique identifier of the user accessing the service.
            simple.read: reading scope

[tkrop]

Thanks for reporting. We are missing the resources to act on this. Any contribution is welcome.