GCP API Gateway路径参数设required为false时报schema不允许属性错误

• 首先是OpenAPI 2.0（Swagger 2.0）规范限制：所有声明在路径里的占位参数（in: path类型的参数）必须设置required: true，不允许设为可选。路径本身的结构决定了占位符如果缺失会导致路由匹配逻辑混乱，这是OpenAPI各版本通用的强制规则。
• 其次是混淆了OpenAPI 2.0和3.0的参数定义语法：
  1. OpenAPI 2.0的参数类型、默认值直接写在参数根层级，不需要schema字段，添加schema反而会被判定为非法多余字段
  2. 当你把path参数的required设为false时，Cloud Endpoint的校验逻辑触发了规则混乱，先后抛出了要求加schema、加了schema又判定多余的矛盾报错，本质都是path参数设为可选触发的校验异常。

要实现id_可选的业务需求，有两种合规的修改方式：

方案1：拆分两个路径定义（保留路径参数写法） #

将原来的单路径拆分为带id_和不带id_的两个路径，分别配置，两者可以复用同一个后端业务逻辑：

paths:
  # 不带id_的路径
  /service/{route}:
    get:
      summary: <summary>
      operationId: serviceWithoutId
      parameters: 
        - in: path
          name: route
          type: string
          required: true
      x-google-backend:
        address: http://<URL_HERE>/{route}
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60.0
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  # 带id_的路径
  /service/{route}/{id_}:
    get:
      summary: <summary> 
      operationId: serviceWithId
      parameters: 
        - in: path
          name: route
          type: string
          required: true
        - in: path
          name: id_
          type: string
          required: true
      x-google-backend:
        address: http://<URL_HERE>/{route}/{id_}
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60.0
      responses:
        '200':
          description: A successful response
          schema:
            type: string

后端收到请求后自行判断id_是否存在即可，符合原有业务逻辑。

方案2：将id_改为查询参数（更简洁） #

把可选的id_从路径占位符移到查询参数，查询参数天然支持设置为可选、配置默认值：

paths:
  /service/{route}:
    get:
      summary: <summary> 
      operationId: service
      parameters: 
        - in: path
          name: route
          type: string
          required: true
        - in: query
          name: id_
          type: string
          required: false
          default: ""
      x-google-backend:
        address: http://<URL_HERE>/{route}
        path_translation: APPEND_PATH_TO_ADDRESS
        deadline: 60.0
      responses:
        '200':
          description: A successful response
          schema:
            type: string

配置path_translation: APPEND_PATH_TO_ADDRESS后，查询参数会自动附加到后端请求地址上，不需要额外配置。

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