@redocly/openapi-core 1.0.0-beta.119 → 1.0.0-beta.121

package/src/config/__tests__/config.test.ts

@@ -44,8 +44,10 @@ const testConfig: Config = {
     preprocessors: { oas2: {}, oas3_0: {}, oas3_1: {} },
     decorators: { oas2: {}, oas3_0: {}, oas3_1: {} },
   } as unknown as StyleguideConfig,
-  'features.openapi': {},
-  'features.mockServer': {},
+  theme: {
+    openapi: {},
+    mockServer: {},
+  },
   resolve: { http: { headers: [] } },
   organization: 'redocly-test',
   files: [],
@@ -66,8 +68,6 @@ describe('getMergedConfig', () => {
           },
         },
         "configFile": "redocly.yaml",
-        "features.mockServer": Object {},
-        "features.openapi": Object {},
         "files": Array [],
         "organization": "redocly-test",
         "rawConfig": Object {
@@ -81,8 +81,6 @@ describe('getMergedConfig', () => {
               },
             },
           },
-          "features.mockServer": Object {},
-          "features.openapi": Object {},
           "files": Array [],
           "organization": "redocly-test",
           "styleguide": Object {
@@ -92,6 +90,7 @@ describe('getMergedConfig', () => {
               "operation-summary": "warn",
             },
           },
+          "theme": Object {},
         },
         "region": undefined,
         "resolve": Object {
@@ -139,6 +138,7 @@ describe('getMergedConfig', () => {
             },
           },
         },
+        "theme": Object {},
       }
     `);
   });
@@ -164,8 +164,6 @@ describe('getMergedConfig', () => {
           },
         },
         "configFile": "redocly.yaml",
-        "features.mockServer": Object {},
-        "features.openapi": Object {},
         "files": Array [],
         "organization": "redocly-test",
         "rawConfig": Object {
@@ -179,8 +177,6 @@ describe('getMergedConfig', () => {
               },
             },
           },
-          "features.mockServer": Object {},
-          "features.openapi": Object {},
           "files": Array [],
           "organization": "redocly-test",
           "styleguide": Object {
@@ -192,6 +188,7 @@ describe('getMergedConfig', () => {
               "operation-summary": "error",
             },
           },
+          "theme": Object {},
         },
         "region": undefined,
         "resolve": Object {
@@ -244,6 +241,7 @@ describe('getMergedConfig', () => {
             },
           },
         },
+        "theme": Object {},
       }
     `);
   });

package/src/config/__tests__/utils.test.ts

@@ -41,8 +41,10 @@ const rawTestConfig: RawConfig = {
   resolve: {
     http: { headers: [{ matches: '*', name: 'all', envVariable: 'all' }] },
   },
-  'features.openapi': {
-    disableSidebar: true,
+  theme: {
+    openapi: {
+      disableSidebar: true,
+    },
   },
 };
 
@@ -63,8 +65,10 @@ const flatTestConfig: FlatRawConfig = {
     http: { headers: [{ matches: '*', name: 'all', envVariable: 'all' }] },
     doNotResolveExamples: true,
   },
-  'features.openapi': {
-    disableSidebar: true,
+  theme: {
+    openapi: {
+      disableSidebar: true,
+    },
   },
 };
 
@@ -85,12 +89,15 @@ describe('transformConfig', () => {
             },
           },
         },
-        "features.openapi": undefined,
         "styleguide": Object {
           "rules": Object {
             "operation-4xx-response": "warn",
           },
         },
+        "theme": Object {
+          "mockServer": Object {},
+          "openapi": Object {},
+        },
       }
     `);
   });
@@ -110,12 +117,15 @@ describe('transformConfig', () => {
             "root": "file.yaml",
           },
         },
-        "features.openapi": undefined,
         "styleguide": Object {
           "rules": Object {
             "operation-4xx-response": "warn",
           },
         },
+        "theme": Object {
+          "mockServer": Object {},
+          "openapi": Object {},
+        },
       }
     `);
   });
@@ -140,4 +150,55 @@ describe('transformConfig', () => {
       `Do not use 'lint', 'styleguide' and flat syntax together. \nSee more about the configuration in the docs: https://redocly.com/docs/cli/configuration/ \n`
     );
   });
+  it('should throw an error if both `features.openapi` and `theme` syntaxes used together', () => {
+    const testRawConfig: RawConfig & DeprecatedInRawConfig = {
+      apis: {
+        'test@v1': {
+          root: 'root.yaml',
+          styleguide: {
+            extends: ['recommended'],
+            rules: { 'operation-2xx-response': 'error' },
+          },
+        },
+      },
+      'features.openapi': {
+        disableSidebar: true,
+      },
+      theme: {
+        openapi: {
+          disableSidebar: true,
+        },
+      },
+    };
+    expect(() => utils.transformConfig(testRawConfig)).toThrowError(
+      `Do not use 'features.openapi' field. Use 'theme.openapi' instead. `
+    );
+  });
+  it('should transform referenceDocs config into theme.openapi', () => {
+    const testRawConfig: RawConfig & DeprecatedInRawConfig = {
+      referenceDocs: {
+        disableSidebar: true,
+      },
+    };
+    expect(utils.transformConfig(testRawConfig)).toEqual({
+      apis: undefined,
+      styleguide: undefined,
+      theme: { mockServer: {}, openapi: { disableSidebar: true } },
+    });
+  });
+  it('should transform "features.openapi" config into theme.openapi', () => {
+    const testRawConfig: RawConfig & DeprecatedInRawConfig = {
+      'features.openapi': {
+        disableSidebar: true,
+      },
+    };
+    expect(utils.transformConfig(testRawConfig)).toEqual({
+      apis: undefined,
+      'features.openapi': {
+        disableSidebar: true,
+      },
+      styleguide: undefined,
+      theme: { mockServer: {}, openapi: { disableSidebar: true } },
+    });
+  });
 });

package/src/config/config.ts

@@ -18,6 +18,7 @@ import type {
   ResolvedStyleguideConfig,
   RuleConfig,
   RuleSettings,
+  ThemeRawConfig,
 } from './types';
 import { getResolveConfig } from './utils';
 
@@ -304,15 +305,13 @@ export class Config {
   resolve: ResolveConfig;
   licenseKey?: string;
   region?: Region;
-  'features.openapi': Record<string, any>;
-  'features.mockServer'?: Record<string, any>;
+  theme: ThemeRawConfig;
   organization?: string;
   files: string[];
   constructor(public rawConfig: ResolvedConfig, public configFile?: string) {
     this.apis = rawConfig.apis || {};
     this.styleguide = new StyleguideConfig(rawConfig.styleguide || {}, configFile);
-    this['features.openapi'] = rawConfig['features.openapi'] || {};
-    this['features.mockServer'] = rawConfig['features.mockServer'] || {};
+    this.theme = rawConfig.theme || {};
     this.resolve = getResolveConfig(rawConfig?.resolve);
     this.region = rawConfig.region;
     this.organization = rawConfig.organization;

package/src/config/types.ts

@@ -145,16 +145,16 @@ export type DeprecatedInRawConfig = {
   styleguide?: StyleguideRawConfig;
   referenceDocs?: Record<string, any>;
   apis?: Record<string, Api & DeprecatedInApi>;
-};
+} & DeprecatedFeaturesConfig;
 
 export type Api = {
   root: string;
   styleguide?: ApiStyleguideRawConfig;
-} & FeaturesConfig;
+} & ThemeConfig;
 
 export type DeprecatedInApi = {
   lint?: ApiStyleguideRawConfig;
-};
+} & DeprecatedFeaturesConfig;
 
 export type ResolvedApi = Omit<Api, 'styleguide'> & {
   styleguide: ResolvedStyleguideConfig;
@@ -168,7 +168,7 @@ export type RawConfig = {
   region?: Region;
   organization?: string;
   files?: string[];
-} & FeaturesConfig;
+} & ThemeConfig;
 
 export type FlatApi = Omit<Api, 'styleguide'> &
   Omit<ApiStyleguideRawConfig, 'doNotResolveExamples'>;
@@ -177,18 +177,27 @@ export type FlatRawConfig = Omit<RawConfig, 'styleguide' | 'resolve' | 'apis'> &
   Omit<StyleguideRawConfig, 'doNotResolveExamples'> & {
     resolve?: RawResolveConfig;
     apis?: Record<string, FlatApi>;
-  };
+  } & ThemeRawConfig;
 
 export type ResolvedConfig = Omit<RawConfig, 'apis' | 'styleguide'> & {
   apis: Record<string, ResolvedApi>;
   styleguide: ResolvedStyleguideConfig;
 };
 
-type FeaturesConfig = {
+type DeprecatedFeaturesConfig = {
   'features.openapi'?: Record<string, any>;
   'features.mockServer'?: Record<string, any>;
 };
 
+export type ThemeConfig = {
+  theme?: ThemeRawConfig;
+};
+
+export type ThemeRawConfig = {
+  openapi?: Record<string, any>;
+  mockServer?: Record<string, any>;
+};
+
 export type RulesFields =
   | 'rules'
   | 'oas2Rules'

package/src/config/utils.ts

@@ -19,6 +19,7 @@ import type {
   ResolvedStyleguideConfig,
   RulesFields,
   StyleguideRawConfig,
+  ThemeConfig,
 } from './types';
 import { logger, colorize } from '../logger';
 
@@ -225,13 +226,9 @@ export function getMergedConfig(config: Config, apiName?: string): Config {
             extendPaths,
             pluginPaths,
           },
-          'features.openapi': {
-            ...config['features.openapi'],
-            ...config.apis[apiName]?.['features.openapi'],
-          },
-          'features.mockServer': {
-            ...config['features.mockServer'],
-            ...config.apis[apiName]?.['features.mockServer'],
+          theme: {
+            ...config.rawConfig.theme,
+            ...config.apis[apiName]?.theme,
           },
           files: [...config.files, ...(config.apis?.[apiName]?.files ?? [])],
           // TODO: merge everything else here
@@ -241,10 +238,11 @@ export function getMergedConfig(config: Config, apiName?: string): Config {
     : config;
 }
 
-function checkForDeprecatedFields(
+export function checkForDeprecatedFields(
   deprecatedField: keyof (DeprecatedInRawConfig & RawConfig),
   updatedField: keyof FlatRawConfig | undefined,
-  rawConfig: DeprecatedInRawConfig & RawConfig & FlatRawConfig
+  rawConfig: DeprecatedInRawConfig & RawConfig & FlatRawConfig,
+  updatedObject: keyof FlatRawConfig | undefined
 ): void {
   const isDeprecatedFieldInApis =
     rawConfig.apis &&
@@ -261,8 +259,12 @@ function checkForDeprecatedFields(
     showErrorForDeprecatedField(deprecatedField, updatedField);
   }
 
+  if (rawConfig[deprecatedField] && updatedObject && rawConfig[updatedObject]) {
+    showErrorForDeprecatedField(deprecatedField, updatedField, updatedObject);
+  }
+
   if (rawConfig[deprecatedField] || isDeprecatedFieldInApis) {
-    showWarningForDeprecatedField(deprecatedField, updatedField);
+    showWarningForDeprecatedField(deprecatedField, updatedField, updatedObject);
   }
 }
 
@@ -271,16 +273,18 @@ export function transformConfig(
 ): RawConfig {
   const migratedFields: [
     keyof (DeprecatedInRawConfig & RawConfig),
-    keyof FlatRawConfig | undefined
+    keyof FlatRawConfig | undefined,
+    keyof ThemeConfig | undefined
   ][] = [
-    ['apiDefinitions', 'apis'],
-    ['referenceDocs', 'features.openapi'],
-    ['lint', undefined],
-    ['styleguide', undefined],
+    ['apiDefinitions', 'apis', undefined],
+    ['referenceDocs', 'openapi', 'theme'],
+    ['lint', undefined, undefined],
+    ['styleguide', undefined, undefined],
+    ['features.openapi', 'openapi', 'theme'],
   ];
 
-  for (const [deprecatedField, updatedField] of migratedFields) {
-    checkForDeprecatedFields(deprecatedField, updatedField, rawConfig);
+  for (const [deprecatedField, updatedField, updatedObject] of migratedFields) {
+    checkForDeprecatedFields(deprecatedField, updatedField, rawConfig, updatedObject);
   }
 
   const { apis, apiDefinitions, referenceDocs, lint, ...rest } = rawConfig;
@@ -288,7 +292,17 @@ export function transformConfig(
   const { styleguideConfig, rawConfigRest } = extractFlatConfig(rest);
 
   return {
-    'features.openapi': referenceDocs,
+    theme: {
+      openapi: {
+        ...referenceDocs,
+        ...rawConfig['features.openapi'],
+        ...rawConfig.theme?.openapi,
+      },
+      mockServer: {
+        ...rawConfig['features.mockServer'],
+        ...rawConfig.theme?.mockServer,
+      },
+    },
     apis: transformApis(apis) || transformApiDefinitionsToApis(apiDefinitions),
     styleguide: styleguideConfig || lint,
     ...rawConfigRest,

package/src/decorators/common/info-override.ts

@@ -0,0 +1,15 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+
+export const InfoOverride: Oas3Decorator | Oas2Decorator = (newInfo) => {
+  return {
+    Info: {
+      leave(info) {
+        if (typeof newInfo !== 'object' || Array.isArray(newInfo) || newInfo === null) {
+          throw new Error(`"info-override" decorator should be called with an object`);
+        }
+        const { severity: _, ...rest } = newInfo;
+        Object.assign(info, rest);
+      },
+    },
+  };
+};

package/src/decorators/oas2/index.ts

@@ -3,6 +3,7 @@ import { RegistryDependencies } from '../common/registry-dependencies';
 import { OperationDescriptionOverride } from '../common/operation-description-override';
 import { TagDescriptionOverride } from '../common/tag-description-override';
 import { InfoDescriptionOverride } from '../common/info-description-override';
+import { InfoOverride } from '../common/info-override';
 import { RemoveXInternal } from '../common/remove-x-internal';
 import { FilterIn } from '../common/filters/filter-in';
 import { FilterOut } from '../common/filters/filter-out';
@@ -12,6 +13,7 @@ export const decorators = {
   'operation-description-override': OperationDescriptionOverride as Oas2Decorator,
   'tag-description-override': TagDescriptionOverride as Oas2Decorator,
   'info-description-override': InfoDescriptionOverride as Oas2Decorator,
+  'info-override': InfoOverride as Oas2Decorator,
   'remove-x-internal': RemoveXInternal as Oas2Decorator,
   'filter-in': FilterIn as Oas2Decorator,
   'filter-out': FilterOut as Oas2Decorator,

package/src/decorators/oas3/index.ts

@@ -3,6 +3,7 @@ import { RegistryDependencies } from '../common/registry-dependencies';
 import { OperationDescriptionOverride } from '../common/operation-description-override';
 import { TagDescriptionOverride } from '../common/tag-description-override';
 import { InfoDescriptionOverride } from '../common/info-description-override';
+import { InfoOverride } from '../common/info-override';
 import { RemoveXInternal } from '../common/remove-x-internal';
 import { FilterIn } from '../common/filters/filter-in';
 import { FilterOut } from '../common/filters/filter-out';
@@ -13,6 +14,7 @@ export const decorators = {
   'operation-description-override': OperationDescriptionOverride as Oas3Decorator,
   'tag-description-override': TagDescriptionOverride as Oas3Decorator,
   'info-description-override': InfoDescriptionOverride as Oas3Decorator,
+  'info-override': InfoOverride as Oas3Decorator,
   'remove-x-internal': RemoveXInternal as Oas3Decorator,
   'filter-in': FilterIn as Oas3Decorator,
   'filter-out': FilterOut as Oas3Decorator,

package/src/resolve.ts

@@ -276,7 +276,11 @@ export async function resolveDocument(opts: {
         if (propType === undefined) propType = type.additionalProperties;
         if (typeof propType === 'function') propType = propType(propValue, propName);
         if (propType === undefined) propType = unknownType;
-        if (type.extensionsPrefix && propName.startsWith(type.extensionsPrefix)) {
+        if (
+          type.extensionsPrefix &&
+          propName.startsWith(type.extensionsPrefix) &&
+          propType === unknownType
+        ) {
           propType = SpecExtension;
         }
 

package/src/rules/__tests__/fixtures/code-sample.php

@@ -0,0 +1,9 @@
+$form = new \PetStore\Entities\Pet();
+$form->setPetType("Dog");
+$form->setName("Rex");
+// set other fields
+try {
+    $pet = $client->pets()->create($form);
+} catch (UnprocessableEntityException $e) {
+    var_dump($e->getErrors());
+}

package/src/rules/__tests__/no-unresolved-refs.test.ts

@@ -165,4 +165,93 @@ describe('oas3 boolean-parameter-prefixes', () => {
       ]
     `);
   });
+
+  it('should not report on refs inside specification extensions', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        components:
+          requestBodies:
+            a:
+              content:
+                application/json:
+                  schema:
+                    type: object
+        x-webhooks:
+          test:
+            put:
+              requestBody:
+                $ref: '#/components/requestBodies/a'
+      `,
+      path.join(__dirname, 'foobar.yaml')
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'no-unresolved-refs': 'error',
+      }),
+    });
+
+    expect(replaceSourceWithRef(results, __dirname)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on nested refs inside specification extensions', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.0.0
+        x-test:
+          prop:
+            $ref: 'fixtures/ref.yaml'
+        paths:
+          '/test':
+            get:
+              x-codeSamples:
+                - lang: PHP
+                  source:
+                    $ref: 'fixtures/code-sample.php'
+      `,
+      path.join(__dirname, 'foobar.yaml')
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'no-unresolved-refs': 'error',
+      }),
+    });
+
+    expect(replaceSourceWithRef(results, __dirname)).toMatchInlineSnapshot(`Array []`);
+  });
+
+  it('should not report on nested refs inside specification extensions for 3.1', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        x-test:
+          prop:
+            $ref: 'fixtures/ref.yaml'
+        paths:
+          '/test':
+            get:
+              x-codeSamples:
+                - lang: PHP
+                  source:
+                    $ref: 'fixtures/code-sample.php'
+      `,
+      path.join(__dirname, 'foobar.yaml')
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'no-unresolved-refs': 'error',
+      }),
+    });
+
+    expect(replaceSourceWithRef(results, __dirname)).toMatchInlineSnapshot(`Array []`);
+  });
 });

package/src/rules/common/__tests__/operation-2xx-response.test.ts

@@ -125,4 +125,68 @@ describe('Oas3 operation-2xx-response', () => {
       ]
     `);
   });
+
+  it('should report missing 2xx response in webhooks when enabled', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.1.0
+          webhooks:
+            '/test/':
+              put:
+                responses:
+                  400:
+                    description: success response
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'operation-2xx-response': { severity: 'error', validateWebhooks: true },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/webhooks/~1test~1/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`2XX\` response.",
+          "ruleId": "operation-2xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report missing 2xx response in webhooks when not enabled', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          x-webhooks:
+            '/test/':
+              put:
+                responses:
+                  400:
+                    description: success response
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'operation-2xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });

package/src/rules/common/__tests__/operation-4xx-response.test.ts

@@ -164,4 +164,68 @@ describe('Oas3 operation-4xx-response', () => {
       ]
     `);
   });
+
+  it('should report missing 4xx response in webhooks when enabled', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.1.0
+          webhooks:
+            '/test/':
+              put:
+                responses:
+                  200:
+                    description: success response
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({
+        'operation-4xx-response': { severity: 'error', validateWebhooks: true },
+      }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "location": Array [
+            Object {
+              "pointer": "#/webhooks/~1test~1/put/responses",
+              "reportOnKey": true,
+              "source": "foobar.yaml",
+            },
+          ],
+          "message": "Operation must have at least one \`4XX\` response.",
+          "ruleId": "operation-4xx-response",
+          "severity": "error",
+          "suggest": Array [],
+        },
+      ]
+    `);
+  });
+
+  it('should not report missing 4xx response in webhooks when not enabled', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.0.0
+          x-webhooks:
+            '/test/':
+              put:
+                responses:
+                  200:
+                    description: success response
+        `,
+      'foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await makeConfig({ 'operation-4xx-response': 'error' }),
+    });
+
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`Array []`);
+  });
 });