Path parameter in OpenAPI yaml file is not recognized

Question

I am having an issue with this code in an OpenAPI Description.

      /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'
        - mstatus:
            in: path
            name: mstatus
            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

I'm not seeing any errors flagged in either Swagger Preview or Redoc but the parameter is not listed in the documentation they produce. Swagger Preview just shows () for the parameter name and Redoc shows a type of any but no parameter name. Swagger Hub just doesn't list it at all.

I've tried defining mstatus as a global parameter and then referencing it from the path but the same problem occurs, so I think there must be a problem in the parameter definition.

The other possibility is that all the other $ref parameters refer to query parameters and this one is a path parameter.

Any ideas on how I can fix this?

Answer 1

Path parameters must be defined with a specific structure, and your current definition incorrectly nests the parameter details under the mstatus key, which is causing the tools to fail in interpreting it correctly. Correcting the Definition

corrected OpenAPI path definition:

    /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'
          - name: mstatus
            in: path
            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