A reusable parameter is an OpenAPI Parameter Object stored under components.parameters and referenced wherever the same request parameter must remain consistent. Centralization reduces duplication while allowing a reference-specific description override. section 17.3.2 section 17.8
Choose the reuse level that matches the design problem:
- Use a path-level parameters list when every operation under one path shares the parameter. section 17.3
- Use components.parameters when the parameter is shared across different paths or operations. section 17.3.2
- Use one reusable object query parameter for a group such as pagination instead of repeating individual parameters. section 17.3.3
Sharing a product identifier
Define ProductId once under components.parameters with name: productId, in: path, and required: true. Reference it from /products/{productId} and /products/{productId}/suppliers with $ref: "#/components/parameters/ProductId". A second path may add a local description without redefining the parameter. section 17.3.2
Grouping pagination parameters
Define a reusable query parameter whose schema is an object with next and limit properties. Reference it once in a search operation; default serialization represents the request as .../?next=s00999&limit=10. Document this representation because tools may render it unclearly. section 17.3.3
