如何用OpenAPI描述API响应与URL参数匹配的通用动态行为？

当然可以用OpenAPI泛化描述这个行为，不用依赖具体示例值，同时能让Mock工具识别并生成匹配的响应。具体写法如下：

1. 明确定义路径参数 #

首先在路径中声明resource-id参数，指定其类型和必要性，让OpenAPI能识别这个输入参数：

paths:
  /create/my-resource/{resource-id}:
    post:
      parameters:
        - name: resource-id
          in: path
          required: true
          schema:
            type: string  # 可根据实际需求改为integer等类型
          description: 待创建资源的唯一标识ID

2. 在响应Schema中说明匹配规则并配置Mock逻辑 #

在响应的Schema里，给id字段添加清晰的描述，明确它与路径参数resource-id的值完全一致；同时如果你的Mock工具支持参数引用表达式（比如Postman、Stoplight、Mockoon等），可以在example字段中写入表达式，让Mock自动生成匹配的值：

responses:
        '201':
          description: 资源创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string  # 类型需和路径参数保持一致
                    description: 与请求路径中传入的`resource-id`完全匹配的资源ID
                    example: '{{request.path.resource-id}}'  # Mock工具会自动替换为实际传入的参数值
                  # 这里可以添加其他响应字段
                required:
                  - id

补充说明 #

OpenAPI规范本身没有原生语法来强制响应字段等于路径参数，但通过清晰的description可以明确告知API使用者这个行为；而example中的表达式则能让支持的Mock工具自动遵循该逻辑生成响应，无需手动指定具体ID值。如果使用的Mock工具不支持这种表达式，也可以通过自定义扩展字段（比如x-mock-rule）来标注匹配规则，具体语法需参考工具文档。

内容的提问来源于stack exchange，提问作者Maths noob