How to fix a missing path parameter declaration in OpenAPI

A path template such as /users/{userId} must have a matching parameter with name: userId and in: path. Writing the variable in the URL does not declare the parameter by itself.

Broken YAML

The path contains {userId}, but the operation has no parameters entry:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      operationId: getUser
      responses:
        '200':
          description: User returned

Why it fails

The OpenAPI path templating rule requires each template expression to match a Path Parameter Object. Parameter names are case-sensitive, so {userId} does not match name: userid.

You can declare the parameter on the operation or on the Path Item. A Path Item declaration applies to every operation under that path. An operation declaration applies to only that operation.

Corrected YAML

Add a required path parameter with the exact template name:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User returned

If several operations use the same template variable, move the same Parameter Object to parameters directly under /users/{userId}.

OpenAPI 3.0 vs 3.1

The declaration rule is the same in OpenAPI 3.0 and OpenAPI 3.1. Both versions require an exact name match and required: true for every path parameter. Schema dialect changes do not change path templating.

Validate the fix

Open the Sourced OpenAPI validator, paste the complete document, and select Validate spec. The report names each URL template variable that has no matching path parameter.

You can also run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

If the parameter exists but has required: false, use the path parameter required guide.