RAML 1.0中如何引入自定义安全模式？原0.8配置失效

RAML v1.0对安全方案的定义和引用机制做了不少调整，你原来v0.8的写法自然会失效。下面是一步步的正确配置方法：

1. 调整外部安全方案的结构 #

v1.0要求每个安全方案必须明确指定type，并且通过describedBy字段定义该安全机制的请求参数、错误响应等规则。你之前的外部.raml文件需要改成符合v1.0规范的完整结构，比如你的http_api_sign_v1.91_dsig.raml可以调整为：

type: x-custom-api-sign # 自定义安全类型需加x-前缀，标准类型如basic/oauth2可直接用
describedBy:
  headers:
    X-Api-Signature:
      description: 生成的API签名串
      type: string
    X-Request-Timestamp:
      description: 请求发起的时间戳
      type: string
  responses:
    401:
      description: 签名验证失败，返回错误信息

2. 在主RAML文件中正确引用 #

主文件里的securitySchemes和securedBy写法也有变化，正确配置示例如下：

#%RAML 1.0
title: Your Target API
mediaType: application/json

# 引入自定义安全方案
securitySchemes:
  highlysensitive: !include ./securitySchemas/http_api_sign_v1.91_dsig.raml

# 全局应用该安全方案
securedBy:
  - highlysensitive: {} # 无权限范围(scopes)时用{}占位，有scopes可写 { scopes: [read, write] }

关键差异说明 #

• v0.8中!include可以直接指向简化的安全模式，但v1.0要求外部文件必须是包含type和describedBy的完整安全方案结构。
• securedBy在v1.0中支持数组或对象格式，即使不需要指定权限范围，也需要用{}来占位，这是和v0.8的核心区别之一。

如果你的签名机制有额外配置需求（比如指定加密算法），还可以在安全方案里添加settings字段补充：

type: x-custom-api-sign
describedBy:
  # ... 头部和响应定义
settings:
  signatureAlgorithm: HMAC-SHA256
  secretKeyHeader: X-Api-Secret

内容的提问来源于stack exchange，提问作者Charu Jain