@redocly/openapi-core 1.4.1 → 1.6.0

package/src/config/config-resolvers.ts

@@ -1,7 +1,7 @@
 import * as path from 'path';
 import { isAbsoluteUrl } from '../ref-utils';
 import { pickDefined } from '../utils';
-import { BaseResolver } from '../resolve';
+import { resolveDocument, BaseResolver } from '../resolve';
 import { defaultPlugin } from './builtIn';
 import {
   getResolveConfig,
@@ -11,6 +11,14 @@ import {
   prefixRules,
   transformConfig,
 } from './utils';
+import { isBrowser } from '../env';
+import { isNotString, isString, isDefined, parseYaml, keysOf } from '../utils';
+import { Config } from './config';
+import { colorize, logger } from '../logger';
+import { asserts, buildAssertCustomFunction } from '../rules/common/assertions/asserts';
+import { normalizeTypes } from '../types';
+import { ConfigTypes } from '../types/redocly-yaml';
+
 import type {
   StyleguideRawConfig,
   ApiStyleguideRawConfig,
@@ -21,17 +29,39 @@ import type {
   RuleConfig,
   DeprecatedInRawConfig,
 } from './types';
-import { isBrowser } from '../env';
-import { isNotString, isString, isDefined, parseYaml, keysOf } from '../utils';
-import { Config } from './config';
-import { colorize, logger } from '../logger';
-import {
-  Asserts,
-  AssertionFn,
-  asserts,
-  buildAssertCustomFunction,
-} from '../rules/common/assertions/asserts';
 import type { Assertion, AssertionDefinition, RawAssertion } from '../rules/common/assertions';
+import type { Asserts, AssertionFn } from '../rules/common/assertions/asserts';
+import type { BundleOptions } from '../bundle';
+import type { Document, ResolvedRefMap } from '../resolve';
+
+export async function resolveConfigFileAndRefs({
+  configPath,
+  externalRefResolver = new BaseResolver(),
+  base = null,
+}: Omit<BundleOptions, 'config'> & { configPath?: string }): Promise<{
+  document: Document;
+  resolvedRefMap: ResolvedRefMap;
+}> {
+  if (!configPath) {
+    throw new Error('Reference to a config is required.\n');
+  }
+
+  const document = await externalRefResolver.resolveDocument(base, configPath, true);
+
+  if (document instanceof Error) {
+    throw document;
+  }
+
+  const types = normalizeTypes(ConfigTypes);
+
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.ConfigRoot,
+    externalRefResolver,
+  });
+
+  return { document, resolvedRefMap };
+}
 
 export async function resolveConfig(rawConfig: RawConfig, configPath?: string): Promise<Config> {
   if (rawConfig.styleguide?.extends?.some(isNotString)) {

package/src/config/load.ts

@@ -1,20 +1,17 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { RedoclyClient } from '../redocly';
-import { isEmptyObject, loadYaml, doesYamlFileExist } from '../utils';
+import { isEmptyObject, doesYamlFileExist } from '../utils';
 import { parseYaml } from '../js-yaml';
 import { Config, DOMAINS } from './config';
 import { ConfigValidationError, transformConfig } from './utils';
-import { resolveConfig } from './config-resolvers';
+import { resolveConfig, resolveConfigFileAndRefs } from './config-resolvers';
+import { bundleConfig } from '../bundle';
 
-import type {
-  DeprecatedInRawConfig,
-  FlatRawConfig,
-  RawConfig,
-  RawUniversalConfig,
-  Region,
-} from './types';
-import { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
+import type { Document } from '../resolve';
+import type { RegionalTokenWithValidity } from '../redocly/redocly-client-types';
+import type { RawConfig, RawUniversalConfig, Region } from './types';
+import type { BaseResolver, ResolvedRefMap } from '../resolve';
 
 async function addConfigMetadata({
   rawConfig,
@@ -73,17 +70,30 @@ async function addConfigMetadata({
   );
 }
 
+export type RawConfigProcessor = (
+  rawConfig: Document,
+  resolvedRefMap: ResolvedRefMap
+) => void | Promise<void>;
+
 export async function loadConfig(
   options: {
     configPath?: string;
     customExtends?: string[];
-    processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>;
+    processRawConfig?: RawConfigProcessor;
+    externalRefResolver?: BaseResolver;
     files?: string[];
     region?: Region;
   } = {}
 ): Promise<Config> {
-  const { configPath = findConfig(), customExtends, processRawConfig, files, region } = options;
-  const rawConfig = await getConfig(configPath, processRawConfig);
+  const {
+    configPath = findConfig(),
+    customExtends,
+    processRawConfig,
+    files,
+    region,
+    externalRefResolver,
+  } = options;
+  const rawConfig = await getConfig({ configPath, processRawConfig, externalRefResolver });
 
   const redoclyClient = new RedoclyClient();
   const tokens = await redoclyClient.getTokens();
@@ -116,17 +126,24 @@ export function findConfig(dir?: string): string | undefined {
 }
 
 export async function getConfig(
-  configPath: string | undefined = findConfig(),
-  processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>
+  options: {
+    configPath?: string;
+    processRawConfig?: RawConfigProcessor;
+    externalRefResolver?: BaseResolver;
+  } = {}
 ): Promise<RawConfig> {
+  const { configPath = findConfig(), processRawConfig, externalRefResolver } = options;
   if (!configPath || !doesYamlFileExist(configPath)) return {};
   try {
-    const rawConfig =
-      (await loadYaml<RawConfig & DeprecatedInRawConfig & FlatRawConfig>(configPath)) || {};
+    const { document, resolvedRefMap } = await resolveConfigFileAndRefs({
+      configPath,
+      externalRefResolver,
+    });
     if (typeof processRawConfig === 'function') {
-      await processRawConfig(rawConfig);
+      await processRawConfig(document, resolvedRefMap);
     }
-    return transformConfig(rawConfig);
+    const bundledConfig = await bundleConfig(document, resolvedRefMap);
+    return transformConfig(bundledConfig);
   } catch (e) {
     if (e instanceof ConfigValidationError) {
       throw e;

package/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',

package/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',

package/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',

package/src/lint.ts

@@ -1,13 +1,18 @@
-import { BaseResolver, resolveDocument, Document, makeDocumentFromString } from './resolve';
+import { BaseResolver, resolveDocument, makeDocumentFromString } from './resolve';
 import { normalizeVisitors } from './visitors';
-import { NodeType } from './types';
-import { ProblemSeverity, WalkContext, walkDocument } from './walk';
+import { walkDocument } from './walk';
 import { StyleguideConfig, Config, initRules, defaultPlugin, resolvePlugins } from './config';
 import { normalizeTypes } from './types';
 import { releaseAjvInstance } from './rules/ajv';
 import { SpecVersion, getMajorSpecVersion, detectSpec, getTypes } from './oas-types';
 import { ConfigTypes } from './types/redocly-yaml';
 import { Spec } from './rules/common/spec';
+import { NoUnresolvedRefs } from './rules/no-unresolved-refs';
+
+import type { Document, ResolvedRefMap } from './resolve';
+import type { ProblemSeverity, WalkContext } from './walk';
+import type { NodeType } from './types';
+import type { NestedVisitObject, Oas3Visitor, RuleInstanceConfig } from './visitors';
 
 export async function lint(opts: {
   ref: string;
@@ -102,8 +107,13 @@ export async function lintDocument(opts: {
   return ctx.problems.map((problem) => config.addProblemToIgnore(problem));
 }
 
-export async function lintConfig(opts: { document: Document; severity?: ProblemSeverity }) {
-  const { document, severity } = opts;
+export async function lintConfig(opts: {
+  document: Document;
+  resolvedRefMap?: ResolvedRefMap;
+  severity?: ProblemSeverity;
+  externalRefResolver?: BaseResolver;
+}) {
+  const { document, severity, externalRefResolver = new BaseResolver() } = opts;
 
   const ctx: WalkContext = {
     problems: [],
@@ -117,21 +127,33 @@ export async function lintConfig(opts: { document: Document; severity?: ProblemS
   });
 
   const types = normalizeTypes(ConfigTypes, config);
-  const rules = [
+  const rules: (RuleInstanceConfig & {
+    visitor: NestedVisitObject<unknown, Oas3Visitor | Oas3Visitor[]>;
+  })[] = [
     {
       severity: severity || 'error',
       ruleId: 'configuration spec',
       visitor: Spec({ severity: 'error' }),
     },
+    {
+      severity: severity || 'error',
+      ruleId: 'configuration no-unresolved-refs',
+      visitor: NoUnresolvedRefs({ severity: 'error' }),
+    },
   ];
-  // TODO: check why any is needed
-  const normalizedVisitors = normalizeVisitors(rules as any, types);
-
+  const normalizedVisitors = normalizeVisitors(rules, types);
+  const resolvedRefMap =
+    opts.resolvedRefMap ||
+    (await resolveDocument({
+      rootDocument: document,
+      rootType: types.ConfigRoot,
+      externalRefResolver,
+    }));
   walkDocument({
     document,
     rootType: types.ConfigRoot,
     normalizedVisitors,
-    resolvedRefMap: new Map(),
+    resolvedRefMap,
     ctx,
   });
 

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 = {};