@redocly/openapi-core 1.4.0 → 1.5.0

package/src/rules/oas3/__tests__/array-parameter-serialization.test.ts

@@ -0,0 +1,263 @@
+import { outdent } from 'outdent';
+import { parseYamlToDocument, replaceSourceWithRef, makeConfig } from '../../../../__tests__/utils';
+import { lintDocument } from '../../../lint';
+import { BaseResolver } from '../../../resolve';
+
+describe('oas3 array-parameter-serialization', () => {
+  it('should report on array parameter without style and explode', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: query
+              schema:
+                type: array
+                items:
+                  type: string
+            - name: b
+              in: header
+              schema:
+                type: array
+                items:
+                  type: string     
+      `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error', in: ['query'] },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1test/parameters/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Parameter \`a\` should have \`style\` and \`explode \` fields",
+          "ruleId": "array-parameter-serialization",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report on array parameter with style but without explode', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: query
+              style: form
+              schema:
+                type: array
+                items:
+                  type: string
+      `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error', in: ['query'] },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1test/parameters/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Parameter \`a\` should have \`style\` and \`explode \` fields",
+          "ruleId": "array-parameter-serialization",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should report on parameter without type but with items', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        paths: 
+          /test:
+            parameters: 
+              - name: test only type, path level
+                in: query
+                schema:
+                  type: array # no items
+            get: 
+              parameters: 
+                - name: test only items, operation level
+                  in: header
+                  items: # no type
+                    type: string
+        components: 
+          parameters:
+            TestParameter: 
+              in: cookie
+              name: test only prefixItems, components level
+              prefixItems: # no type or items
+                - type: number    
+              `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error', in: ['query'] },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1test/parameters/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Parameter \`test only type, path level\` should have \`style\` and \`explode \` fields",
+          "ruleId": "array-parameter-serialization",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report on array parameter with style and explode', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: query
+              style: form
+              explode: false
+              schema:
+                type: array
+                items:
+                  type: string
+      `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error', in: ['query'] },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it('should not report non-array parameter without style and explode', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: query
+              schema:
+                type: string
+      `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error', in: ['query'] },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
+
+  it("should report all array parameter without style and explode if property 'in' not defined ", async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        paths:
+          '/test':
+            parameters:
+            - name: a
+              in: query
+              schema:
+                type: array
+                items:
+                  type: string
+            - name: b
+              in: header
+              schema:
+                type: array
+                items:
+                  type: string     
+      `,
+      'foobar.yaml'
+    );
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'array-parameter-serialization': { severity: 'error' },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      [
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1test/parameters/0",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Parameter \`a\` should have \`style\` and \`explode \` fields",
+          "ruleId": "array-parameter-serialization",
+          "severity": "error",
+          "suggest": [],
+        },
+        {
+          "location": [
+            {
+              "pointer": "#/paths/~1test/parameters/1",
+              "reportOnKey": false,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Parameter \`b\` should have \`style\` and \`explode \` fields",
+          "ruleId": "array-parameter-serialization",
+          "severity": "error",
+          "suggest": [],
+        },
+      ]
+    `);
+  });
+});

package/src/rules/oas3/array-parameter-serialization.ts

@@ -0,0 +1,43 @@
+import { Oas3Rule, Oas3Visitor } from '../../visitors';
+import { isRef } from '../../ref-utils';
+import { Oas3_1Schema, Oas3Parameter } from '../../typings/openapi';
+
+export type ArrayParameterSerializationOptions = {
+  in?: string[];
+};
+
+export const ArrayParameterSerialization: Oas3Rule = (
+  options: ArrayParameterSerializationOptions
+): Oas3Visitor => {
+  return {
+    Parameter: {
+      leave(node: Oas3Parameter, ctx) {
+        if (!node.schema) {
+          return;
+        }
+        const schema = isRef(node.schema)
+          ? ctx.resolve<Oas3_1Schema>(node.schema).node
+          : (node.schema as Oas3_1Schema);
+
+        if (schema && shouldReportMissingStyleAndExplode(node, schema, options)) {
+          ctx.report({
+            message: `Parameter \`${node.name}\` should have \`style\` and \`explode \` fields`,
+            location: ctx.location,
+          });
+        }
+      },
+    },
+  };
+};
+
+function shouldReportMissingStyleAndExplode(
+  node: Oas3Parameter,
+  schema: Oas3_1Schema,
+  options: ArrayParameterSerializationOptions
+) {
+  return (
+    (schema.type === 'array' || schema.items || schema.prefixItems) &&
+    (node.style === undefined || node.explode === undefined) &&
+    (!options.in || (node.in && options.in?.includes(node.in)))
+  );
+}

package/src/rules/oas3/index.ts

@@ -52,6 +52,7 @@ import { Operation4xxProblemDetailsRfc7807 } from './operation-4xx-problem-detai
 import { RequiredStringPropertyMissingMinLength } from '../common/required-string-property-missing-min-length';
 import { SpecStrictRefs } from '../common/spec-strict-refs';
 import { ComponentNameUnique } from './component-name-unique';
+import { ArrayParameterSerialization } from './array-parameter-serialization';
 
 export const rules: Oas3RuleSet<'built-in'> = {
   spec: Spec,
@@ -108,6 +109,7 @@ export const rules: Oas3RuleSet<'built-in'> = {
   'required-string-property-missing-min-length': RequiredStringPropertyMissingMinLength,
   'spec-strict-refs': SpecStrictRefs,
   'component-name-unique': ComponentNameUnique,
+  'array-parameter-serialization': ArrayParameterSerialization,
 };
 
 export const preprocessors = {};

package/src/types/oas3_1.ts

@@ -181,6 +181,17 @@ const Schema: NodeType = {
   extensionsPrefix: 'x-',
 };
 
+const SchemaProperties: NodeType = {
+  properties: {},
+  additionalProperties: (value: any) => {
+    if (typeof value === 'boolean') {
+      return { type: 'boolean' };
+    } else {
+      return 'Schema';
+    }
+  },
+};
+
 const SecurityScheme: NodeType = {
   properties: {
     type: { enum: ['apiKey', 'http', 'oauth2', 'openIdConnect', 'mutualTLS'] },
@@ -256,6 +267,7 @@ export const Oas3_1Types: Record<string, NodeType> = {
   Info,
   Root,
   Schema,
+  SchemaProperties,
   License,
   Components,
   NamedPathItems: mapOf('PathItem'),

package/src/types/redocly-yaml.ts

@@ -77,6 +77,7 @@ const builtInOAS3Rules = [
   'response-contains-property',
   'response-mime-type',
   'spec-components-invalid-map-name',
+  'array-parameter-serialization',
 ] as const;
 
 export type BuiltInOAS3RuleId = typeof builtInOAS3Rules[number];

package/src/typings/openapi.ts

@@ -156,6 +156,7 @@ export interface Oas3Schema {
 export type Oas3_1Schema = Oas3Schema & {
   type?: string | string[];
   examples?: any[];
+  prefixItems?: Oas3_1Schema[];
 };
 
 export interface Oas3_1Definition extends Oas3Definition {

package/src/visitors.ts

@@ -204,6 +204,7 @@ type Oas2FlatVisitor = {
   NamedResponses?: VisitFunctionOrObject<Record<string, Oas2Response>>;
   NamedParameters?: VisitFunctionOrObject<Record<string, Oas2Parameter>>;
   SecurityScheme?: VisitFunctionOrObject<Oas2SecurityScheme>;
+  NamedSecuritySchemes?: VisitFunctionOrObject<Record<string, Oas2SecurityScheme>>;
   SpecExtension?: VisitFunctionOrObject<unknown>;
 };
 
@@ -255,18 +256,6 @@ export type Async2Visitor = BaseVisitor &
   Async2NestedVisitor &
   Record<string, VisitFunction<any> | NestedVisitObject<any, Async2NestedVisitor>>;
 
-export type Oas3TransformVisitor = BaseVisitor &
-  Oas3FlatVisitor &
-  Record<string, VisitFunction<any> | VisitObject<any>>;
-
-export type Oas2TransformVisitor = BaseVisitor &
-  Oas2FlatVisitor &
-  Record<string, VisitFunction<any> | VisitObject<any>>;
-
-export type Async2TransformVisitor = BaseVisitor &
-  Async2FlatVisitor &
-  Record<string, VisitFunction<any> | VisitObject<any>>;
-
 export type NestedVisitor<T> = Exclude<T, 'any' | 'ref' | 'Root'>;
 
 export type NormalizedOasVisitors<T extends BaseVisitor> = {
@@ -289,12 +278,12 @@ export type NormalizedOasVisitors<T extends BaseVisitor> = {
 export type Oas3Rule = (options: Record<string, any>) => Oas3Visitor | Oas3Visitor[];
 export type Oas2Rule = (options: Record<string, any>) => Oas2Visitor | Oas2Visitor[];
 export type Async2Rule = (options: Record<string, any>) => Async2Visitor | Async2Visitor[];
-export type Oas3Preprocessor = (options: Record<string, any>) => Oas3TransformVisitor;
-export type Oas2Preprocessor = (options: Record<string, any>) => Oas2TransformVisitor;
-export type Async2Preprocessor = (options: Record<string, any>) => Async2TransformVisitor;
-export type Oas3Decorator = (options: Record<string, any>) => Oas3TransformVisitor;
-export type Oas2Decorator = (options: Record<string, any>) => Oas2TransformVisitor;
-export type Async2Decorator = (options: Record<string, any>) => Async2TransformVisitor;
+export type Oas3Preprocessor = (options: Record<string, any>) => Oas3Visitor;
+export type Oas2Preprocessor = (options: Record<string, any>) => Oas2Visitor;
+export type Async2Preprocessor = (options: Record<string, any>) => Async2Visitor;
+export type Oas3Decorator = (options: Record<string, any>) => Oas3Visitor;
+export type Oas2Decorator = (options: Record<string, any>) => Oas2Visitor;
+export type Async2Decorator = (options: Record<string, any>) => Async2Visitor;
 
 // alias for the latest version supported
 // every time we update it - consider semver