0455569a39
* docs: Start with a more developer and purpose oriented landing page * docs: Clear installation options, autocomplete is a separate guide * docs: update links in installation guide * docs: Move update instructions to be a guide, remove local installation * docs: Remove git documentation from starter project * docs: Add a quicker quickstart * docs: Re-organise and flesh out commands page * docs: add built-in ruleset docs, add concept, start guide * docs: Add a guide for configuring linting * Docs: rename custom rules to assertions * docs: Sort assertion docs and examples alphabetically * docs: clearer linting explanations and signposting of rule types * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * docs: Remove reference to a config object, after user confusion * docs: Add docs-building entrypoint article * docs: Add one-line descriptions alongside rule names * fix: Correct images for docs overview page * docs: Link to custom function in custom plugin docs * fix: Links in rules need updating after this file moved * docs: Add concept article for openapi file wrangling * docs: assertions are now called configurable rules * fix: Broken links and a renamed file * docs: Titles, links, and restructuring * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * fix: Redirect for renamed CLI update guide * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * chore: reduce filesize of images * docs: Detangle the custom/configurable rules vs assertions confusion * fix: labels as well as links to configurable rules * Update docs/guides/configure-rules.md Co-authored-by: Adam Altman <adam@redoc.ly> * fix: Better example wording and fix title case * Update docs/commands/index.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/rules/recommended.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/quickstart.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/rules.md Co-authored-by: Adam Altman <adam@redoc.ly> * chore: rename file built-in-rules.md and corresponding links (#1075) --------- Co-authored-by: Adam Altman <adam@redoc.ly>
2.6 KiB
boolean-parameter-prefixes
Enforces specific and consistent naming for request parameters with boolean type.
When this rule is enabled, the name fields of all boolean parameters in your API must contain one of the configured prefixes.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
flowchart TD
root ==> Paths --> PathItem --> Operation --> Parameter --enforces names for boolean types--> Schema
PathItem --> Parameter
NamedParameter --> Parameter
root ==> components
subgraph components
NamedParameter
end
style Parameter fill:#codaf9,stroke:#0044d4,stroke-width:5px
style Schema fill:#codaf9,stroke:#0044d4,stroke-width:5px
API design principles
Consistency in API design makes APIs easier to use.
Being able to identity boolean types from their names is possible when they use consistent prefixes, such as is or has.
If you saw an API with these parameters, you could identify the boolean parameters by their names:
- orderNumber
- amount
- hasPaid
- shippingService
- isFulfilled
- customerReference
The nuance of being able to identify the boolean parameters helps developers produce and consume APIs.
Configuration
| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off. |
| prefixes | [string] | List of allowed boolean parameter prefixes. Default values are is and has. |
An example configuration:
rules:
boolean-parameter-prefixes: error
The following example configures prefixes:
rules:
boolean-parameter-prefixes:
severity: error
prefixes: ["can", "is", "has"]
Examples
Given the configuration with the prefixes can, is, and has, the following example shows an error.
Example of incorrect boolean parameter prefixes:
schema:
type: object
properties:
belongsToUser:
type: boolean
default: false
Example of correct boolean parameter prefixes:
schema:
type: object
properties:
isUser:
type: boolean
default: false