Description
Parameters are a critical component of any API request. The purpose of this ticket is to create linting rules that enforce best practices for defining and handling parameters.
Conditions of acceptance
- Implement a rule that verifies the 'in' property exists and is an accepted value: “query”, “header”, “path” or “cookie”. This should throw an error if it is not an accepted value. (commit)
- Implement a rule that verifies all parameters have descriptions. This should throw an error if the description is not present.
- Implement a rule that checks parameter options for enums. If an enum is present, then check the description contains an "Available values" list that contains every expected enum option. This should throw an "info" warning for formatting.
- Implement a rule that checks the parameter description is not simply "{parameterName} parameter". This should throw an error, as it means the default value was not customized.
- Implement a rule that verifies parameter name uniqueness per path. In other words, you cannot reuse the same parameter name within the same endpoint. This should throw an error if it is not unique. (commit)
- If some of the above rules are overly complex to implement, separate into dedicated subtask tickets.
Implementation details
For enum available values, see /v1/page/{title}/history]/counts/{type} for an example.
OAS for parameters: https://spec.openapis.org/oas/v3.0.0.html#parameter-object
We are using spectral for ruleset definitions: https://stoplight.io/open-source/spectral. Spectral supports checking for basic formats (eg: exists, specific length), but more sophisticated rules will require custom validation methods.
Existing framework repo: wmf-openapi-linter repository; rulesets here --> https://gitlab.wikimedia.org/toolforge-repos/wmf-openapi-linter/-/blob/main/server/rules/wikimedia-ruleset.js?ref_type=heads
Checking for uniqueness and presence of enum values in the description will be tricky.