Безопасность

Способы авторизации описываются в components.securitySchemes, а применяются полем security — для всего API (в корне документа) или для отдельной операции.

Security Scheme — схема безопасности

type	Назначение	Поля
apiKey	ключ в заголовке, строке запроса или cookie	name, in (header, query, cookie)
http	стандартные схемы HTTP-авторизации	scheme (basic, bearer …), bearerFormat (подсказка, например JWT)
oauth2	OAuth 2.0	flows
openIdConnect	OpenID Connect	openIdConnectUrl

У всех схем есть необязательное description.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    oidc:
      type: openIdConnect
      openIdConnectUrl: https://auth.example.ru/.well-known/openid-configuration

OAuth 2.0

flows описывает поддерживаемые потоки: authorizationCode, clientCredentials, implicit, password. У каждого потока — адреса (authorizationUrl, tokenUrl, refreshUrl) и scopes — области доступа с описаниями.

components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.ru/authorize
          tokenUrl: https://auth.example.ru/token
          scopes:
            orders:read: Чтение заказов
            orders:write: Создание и изменение заказов
        clientCredentials:
          tokenUrl: https://auth.example.ru/token
          scopes:
            orders:read: Чтение заказов

Потоки implicit и password считаются небезопасными и в новых API не рекомендуются.

Security Requirement — применение

security — массив требований. Каждое требование — объект «имя схемы → список областей доступа» (для схем без областей — пустой список). Требования в массиве — альтернативы (достаточно выполнить одно), а схемы внутри одного требования должны выполняться вместе.

openapi: 3.0.3
info:
  title: API заказов
  version: 1.0.0
security:
  - bearerAuth: []
paths:
  /orders:
    get:
      summary: Мои заказы
      responses:
        '200':
          description: Заказы
    post:
      summary: Создать заказ
      security:
        - oauth: [orders:write]
      responses:
        '201':
          description: Заказ создан
  /health:
    get:
      summary: Проверка работоспособности
      security: []
      responses:
        '200':
          description: Сервис работает
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.ru/token
          scopes:
            orders:write: Создание заказов

• корневой security действует для всех операций;
• security операции заменяет корневой;
• security: [] делает операцию доступной без авторизации;
• пример требования «ключ и базовая авторизация вместе»: - { apiKeyHeader: [], basicAuth: [] }; «ключ или токен»: два отдельных элемента массива.