Clear and consistent parameter definitions improve usability and reduce ambiguity for developers. The table below summarizes the aspects of parameter definitions and the corresponding guidelines:
Parameter aspect Guideline
Names Use consistent names across all endpoints. For example, use customerId instead of alternating between id or custId.
Path parameters Always declare required: true and specify schema.type for each path parameter.
Query pagination Standardize pagination by using either limit and cursor or page and pageSize. Document the chosen approach in the parameter description.
Booleans Avoid tri-state confusion. If a boolean parameter is nullable, document its semantics clearly.
Filtering arrays Use repeatable query parameters, for example filter=val1&filter=val2, or comma-separated values (CSV). Document which approach is implemented.
If pagination and filtering are widely used across the API, include a short section in the global description (information section) to explain the standard approach. This ensures consistency and helps developers understand the expected patterns.