feat: create new rule to enforce array parameters format (#1338)

2025-12-09 20:57:44 +00:00 · 2023-11-24 16:18:58 +02:00
parent cf35f76121
commit efb6a453f5
12 changed files with 437 additions and 0 deletions
--- a/docs/rules/array-parameter-serialization.md
+++ b/docs/rules/array-parameter-serialization.md
@@ -0,0 +1,109 @@
+---
+slug: /docs/cli/rules/array-parameter-serialization
+---
+
+# array-parameter-serialization
+
+Enforces the inclusion of `style` and `explode` fields for parameters with array type or parameters with a schema that includes `items` or `prefixItems`.
+
+| OAS | Compatibility |
+| --- | ------------- |
+| 2.0 | ❌            |
+| 3.0 | ✅            |
+| 3.1 | ✅            |
+
+```mermaid
+flowchart TD
+
+root ==> Paths --> PathItem --> Operation --> Parameter --enforces style and explode fields for array 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
+
+Specifying serialization details consistently helps developers understand how to interact with the API effectively.
+
+## Configuration
+
+| Option   | Type     | Description                                                                                                                      |
+| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| severity | string   | Possible values: `off`, `warn`, `error`. Default `off`.                                                                          |
+| in       | [string] | List of valid parameter locations where the rule should be enforced. By default the rule applies to parameters in all locations. |
+
+An example configuration:
+
+```yaml
+rules:
+  array-parameter-serialization:
+    severity: error
+    in:
+      - query
+      - header
+```
+
+## Examples
+
+Given this configuration:
+
+```yaml
+rules:
+  array-parameter-serialization:
+    severity: error
+    in:
+      - query
+```
+
+Example of **incorrect** parameter:
+
+```yaml
+paths:
+  /example:
+    get:
+      parameters:
+        - name: exampleArray
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+```
+
+Example of **correct** parameter:
+
+```yaml
+paths:
+  /example:
+    get:
+      parameters:
+        - name: exampleArray
+          in: query
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+```
+
+## Related rules
+
+- [configurable rules](./configurable-rules.md)
+- [boolean-parameter-prefixes](./boolean-parameter-prefixes.md)
+- [no-invalid-parameter-examples](./no-invalid-parameter-examples.md)
+- [parameter-description](./parameter-description.md)
+- [operation-parameters-unique](./operation-parameters-unique.md)
+
+## Resources
+
+- [Rule source for OAS 3.0 and 3.1](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/oas3/array-parameter-serialization.ts)
+- [OpenAPI Parameter](https://redocly.com/docs/openapi-visual-reference/parameter/) docs