Swagger Editor中Schema错误“不应存在额外属性”含义咨询

我来帮你拆解这个错误——这个提示本质是说你定义的几个API路径不符合OpenAPI 3.0的规范要求，Swagger Editor无法识别这些路径的合法结构，所以把它们标记成了“不应该存在的额外属性”。

错误的核心原因 #

你的YAML文件里主要有两个问题触发了这个错误：

1. 路径变量未完整声明：比如/countries/{countryId}/cinemas/{theatreid}/screens这类路径里包含{countryId}这个路径变量，但你在对应的parameters数组里完全没定义这个参数。OpenAPI 3.0要求所有路径中的变量必须在parameters中明确声明，否则会被判定为无效结构。
2. 参数缺少类型定义：所有参数（包括header里的LBPATH、Accept-Language，还有query参数seatwidth等）都没有指定类型。OpenAPI 3.0要求每个参数必须通过schema字段定义其数据类型（比如字符串、整数），否则编辑器无法识别参数的合法格式。

具体修复示例 #

我拿你文件里的几个路径举例，修复后的写法如下：

修复/buildinfo路径

/buildinfo:
  get:
    description: Returns the build information (Version and Time stamp).
    operationId: getBuildInfo
    parameters:
      - name: LBPATH
        in: header
        schema:
          type: string  # 声明参数为字符串类型
        required: false  # 根据实际业务需求设置是否必填，路径参数必须设为true

修复带countryId的路径（比如/countries/{countryId}/cinemas/{theatreid}/screens）

/countries/{countryId}/cinemas/{theatreid}/screens:
  get:
    description: Returns a list of Auditoriums that is currently running in a specific city. Ordered by movie name in ascending order.
    operationId: getAuditoriumsInTheatre
    parameters:
      - name: countryId  # 新增路径变量的声明
        in: path
        required: true  # 路径参数必须设为必填
        schema:
          type: string  # 根据实际数据类型调整，比如int32
      - name: theatreid
        in: path
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        schema:
          type: string
      - name: LBPATH
        in: header
        schema:
          type: string

通用修复要点 #

• 检查所有路径中的变量（比如{countryId}、{theatreid}），确保每个变量都在parameters数组里有对应的声明，且in字段设为path，required设为true。
• 给每个参数添加schema字段，明确其数据类型（比如type: string、type: integer），如果是整数还可以添加format: int32或int64来更精确定义。
• 对于可选的query或header参数，可以显式设置required: false（默认就是false，显式声明更清晰）。

按照这个思路修复所有报错的路径后，Swagger Editor的这个错误应该就会消失了。

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