OpenAPI YAML路径参数mstatus未被文档工具识别的问题求助

错误原因 #

你写的路径参数mstatus语法不符合OpenAPI规范：在parameters数组中，每个参数应该是一个直接包含参数属性的对象，但你错误地把mstatus作为对象的键，导致解析工具无法正确识别这个参数。

修正后的代码 #

删除mstatus:这一行，直接保留参数的属性配置，同时记得给路径参数添加必填标记：

/members/status/{mstatus}:
  get:
    tags:
      - Members
    summary: Get all members with the specified status
    parameters:
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/group'
      - in: path
        name: mstatus
        required: true # 路径参数必须标记为必填
        description: Define if current or expired members are to be selected.  For expired, use the filter parameter to define when the membership expired
        schema:
          type: string
          enum: [ current, expired ]
          example: expired # Select members with expired membership

关键说明 #

• 路径参数必填规则：路径参数是URL的固定组成部分，必须显式设置required: true，否则部分OpenAPI工具会忽略或解析异常。
• 参数结构规范：parameters数组中的每一项，要么是$ref引用全局参数，要么是直接定义参数的完整属性（in、name、schema等），不能用参数名作为对象键来嵌套定义。

如果之前尝试全局参数引用仍有问题，检查全局参数的定义是否符合规范：确保全局参数的name和路径中的{mstatus}完全一致，且in: path、required: true都正确配置。

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