RAML 1.0如何将UriParameter设置为可选参数？

正确配置方案 #

方案1：双资源声明（适用最常用的/test-api、/test-api/{testId}路径格式） #

这是最符合REST API路径习惯的实现方式，直接声明两个同级资源节点，重复的接口逻辑可以通过RAML的trait或resourceType复用，避免冗余代码：

# 先定义可复用的接口逻辑模板
traits:
  commonTestApiLogic:
    get:
      responses:
        200:
          body: application/json
    # 其他请求方法（post/put等）同样在这里定义

# 匹配无参数的路径 /test-api
/test-api:
  is: [commonTestApiLogic]

# 匹配带参数的路径 /test-api/{testId}
/test-api/{testId}:
  is: [commonTestApiLogic]
  uriParameters:
    testId:
      type: string
      required: true

该配置下/test-api和/test-api/123两个路径都可以正常匹配，实现参数可选的需求。

方案2：单资源同片段声明（符合RAML官方可选URI参数规范） #

如果不想声明两个资源，可以按照官方文档要求，将可选参数和固定文本放在同一个路径片段中，不需要用斜杠分隔参数和固定文本：

/test-api~{testId}:
  uriParameters:
    testId:
      type: string
      required: false

该配置下可以匹配/test-api~（无参数）和/test-api~123（带参数）两个路径。

原有方案失效原因 #

RAML规范明确要求：被斜杠单独包裹的URI参数（即单独作为一个路径片段的参数）即使配置了可选规则也不会生效，这种场景下参数强制为必填，避免出现//这类无意义的路径格式。

• 前两种方案中testId是单独的路径片段，required: false和?标记的可选规则都会被忽略，不传参数就无法匹配到资源。
• 第三种/test-api{testId}的写法会将test-api和参数值合并为一个路径片段，空参数时路径片段为空，自然无法匹配/test-api路径。

内容的提问来源于stack exchange，提问作者Rizwan Shakoor