Redocly/redocly-cli

Add schemeName support to x-security at the workflow level

開放

#2,232 建立於 2025年7月28日

 (0 則留言) (0 個反應) (1 位負責人)TypeScript (222 個分叉)auto 404
RespectType: Enhancementgood first issuep3

倉庫指標

星標
 (1,481 顆星)
PR 合併指標
 (平均合併 3天 4小時) (30 天內合併 70 個 PR)

描述

Is your feature request related to a problem? Please describe.

Currently, in order to define security at the workflow level using x-security, we have to inline the entire security scheme. This leads to duplication when the scheme already exists and is referenced elsewhere in the API description. It makes workflows verbose and harder to maintain.

Describe the solution you'd like

Allow x-security at workflow level to support a schemeName field referencing an existing security scheme (via $sourceDescriptions) instead of requiring the full scheme object. Example:

sourceDescriptions:
  - name: main
    type: openapi
    url: ../main/openapi.yaml

workflows:
  - workflowId: workflowId
    x-security: 
      - schemeName: $sourceDescriptions.main.UserCookie
        values:
          apiKey: {KEY}

Describe alternatives you've considered

The current workaround is to inline the scheme every time:

workflows:
  - workflowId: workflowId
    x-security: 
      - scheme:
          type: apiKey
          in: cookie
          name: accessToken
        values:
          apiKey: {KEY}

This approach is repetitive and error-prone, especially when the same scheme is reused across multiple workflows.

Additional context

Referencing existing schemes improves maintainability and reduces duplication. A common use case is referencing a shared scheme like:

UserCookie:
  $ref: ../common/security/UserCookie.yaml

Which is defined as:

type: apiKey
in: cookie
name: accessToken
description: Default authentication scheme for interaction between browser and API.

References

貢獻者指南