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

.changeset/silver-singers-glow.md

@@ -0,0 +1,6 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Added new rule `array-parameter-serialization` to require that serialization parameters `style` and `explode` are present on array parameters.

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

packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap

@@ -21,6 +21,7 @@ exports[`resolveConfig should ignore minimal from the root and read local file 1
   "oas3_0Decorators": {},
   "oas3_0Preprocessors": {},
   "oas3_0Rules": {
+    "array-parameter-serialization": "off",
     "boolean-parameter-prefixes": "error",
     "component-name-unique": "off",
     "no-empty-servers": "error",
@@ -40,6 +41,7 @@ exports[`resolveConfig should ignore minimal from the root and read local file 1
   "oas3_1Decorators": {},
   "oas3_1Preprocessors": {},
   "oas3_1Rules": {
+    "array-parameter-serialization": "off",
     "boolean-parameter-prefixes": "error",
     "component-name-unique": "off",
     "no-empty-servers": "error",
@@ -125,6 +127,7 @@ exports[`resolveStyleguideConfig should resolve extends with local file config w
   "oas3_0Decorators": {},
   "oas3_0Preprocessors": {},
   "oas3_0Rules": {
+    "array-parameter-serialization": "off",
     "boolean-parameter-prefixes": "error",
     "component-name-unique": "off",
     "no-empty-servers": "error",
@@ -144,6 +147,7 @@ exports[`resolveStyleguideConfig should resolve extends with local file config w
   "oas3_1Decorators": {},
   "oas3_1Preprocessors": {},
   "oas3_1Rules": {
+    "array-parameter-serialization": "off",
     "boolean-parameter-prefixes": "error",
     "component-name-unique": "off",
     "no-empty-servers": "error",

packages/core/src/config/all.ts

@@ -78,6 +78,7 @@ const all: PluginStyleguideConfig<'built-in'> = {
     'component-name-unique': 'error',
     'response-contains-property': 'error',
     'spec-components-invalid-map-name': 'error',
+    'array-parameter-serialization': 'error',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'error',
@@ -101,6 +102,7 @@ const all: PluginStyleguideConfig<'built-in'> = {
     'component-name-unique': 'error',
     'response-contains-property': 'error',
     'spec-components-invalid-map-name': 'error',
+    'array-parameter-serialization': 'error',
   },
   async2Rules: {
     'channels-kebab-case': 'error',

packages/core/src/config/minimal.ts

@@ -66,6 +66,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'warn',
@@ -83,6 +84,7 @@ const minimal: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   async2Rules: {
     'channels-kebab-case': 'off',

packages/core/src/config/recommended-strict.ts

@@ -66,6 +66,7 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'error',
@@ -83,6 +84,7 @@ const recommendedStrict: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   async2Rules: {
     'channels-kebab-case': 'off',

packages/core/src/config/recommended.ts

@@ -66,6 +66,7 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   oas3_1Rules: {
     'no-invalid-media-type-examples': 'warn',
@@ -83,6 +84,7 @@ const recommended: PluginStyleguideConfig<'built-in'> = {
     'request-mime-type': 'off',
     'response-contains-property': 'off',
     'response-mime-type': 'off',
+    'array-parameter-serialization': 'off',
   },
   async2Rules: {
     'channels-kebab-case': 'off',