A parameters list declares non-body request parameters in an OpenAPI path or operation. A path-level list applies one consistent definition to every operation under that path. section 6.4.3 section 6.6.1
Product reference path
For /products/{productReference}, declare the matching parameter at path level. Its name matches the placeholder, in is path, required is true, and schema describes the value. A GET, PUT, or DELETE operation under this path inherits the same definition. section 6.4.3 section 17.3.1
Choose the parameter location and declaration level according to how widely the input applies:
- Use the path-level list for parameters shared by every operation, including path parameters and shared query or header parameters. section 17.3 section 17.3.1
- Use an operation-level list for inputs belonging only to one operation, such as search keywords and category query parameters. section 6.6.1
- Keep parameter schemas aligned with resource properties, and replace duplicated definitions with reusable parameters when consistency must span multiple paths. section 7.6.1 section 17.8
Listing 6.3 Path parameters
...
paths:
...
/products/{productReference}: #1
summary: Product
parameters: #2
- name: productReference #3
in: path #4
required: true #5
schema: {} #5
Inspect the compact OpenAPI listing showing a path-level productReference declaration. section 6.4.3
