feat: add support for Overlay v1 documents

* linting * preprocessors * decorators * type extensions
Redocly · Feb 10, 2025 · b9f71e5 · b9f71e5
1 parent f4cdd75
commit b9f71e5
Show file tree

Hide file tree

Showing 24 changed files with 199 additions and 25 deletions.
diff --git a/.changeset/funny-lobsters-thank.md b/.changeset/funny-lobsters-thank.md
@@ -0,0 +1,6 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Added support for linting, preprocessors, decorators, and type extensions for Overlay v1 documents.
diff --git a/.changeset/stale-starfishes-rule.md b/.changeset/stale-starfishes-rule.md
diff --git a/__tests__/build-docs/build-docs-with-config-option/snapshot.js b/__tests__/build-docs/build-docs-with-config-option/snapshot.js
@@ -4,7 +4,7 @@ exports[`E2E build-docs build docs with config option 1`] = `
 Found nested/redocly.yaml and using theme.openapi options
 Prerendering docs
 
-🎉 bundled successfully in: nested/redoc-static.html (36 KiB) [⏱ <test>ms].
+🎉 bundled successfully in: nested/redoc-static.html (33 KiB) [⏱ <test>ms].
 
 
 `;
diff --git a/__tests__/build-docs/simple-build-docs/snapshot.js b/__tests__/build-docs/simple-build-docs/snapshot.js
@@ -4,7 +4,7 @@ exports[`E2E build-docs simple build-docs 1`] = `
 Found undefined and using theme.openapi options
 Prerendering docs
 
-🎉 bundled successfully in: redoc-static.html (330 KiB) [⏱ <test>ms].
+🎉 bundled successfully in: redoc-static.html (324 KiB) [⏱ <test>ms].
 
 
 `;
diff --git a/packages/cli/src/__tests__/utils.test.ts b/packages/cli/src/__tests__/utils.test.ts
@@ -502,6 +502,7 @@ describe('checkIfRulesetExist', () => {
       async2: {},
       async3: {},
       arazzo1: {},
+      overlay1: {},
     };
     expect(() => checkIfRulesetExist(rules)).toThrowError(
       '⚠️ No rules were configured. Learn how to configure rules: https://redocly.com/docs/cli/rules/'

diff --git a/packages/cli/src/wrapper.ts b/packages/cli/src/wrapper.ts
@@ -38,6 +38,8 @@ export function commandWrapper<T extends CommandOptions>(
         ? 'asyncapi'
         : document?.arazzo
         ? 'arazzo'
+        : document?.overlay
+        ? 'overlay'
         : undefined;
       if (specKeyword) {
         specFullVersion = document[specKeyword] as string;

diff --git a/packages/core/src/bundle.ts b/packages/core/src/bundle.ts
@@ -311,6 +311,11 @@ export function mapTypeToComponent(typeName: string, version: SpecMajorVersion)
         default:
           return null;
       }
+    case SpecMajorVersion.Overlay1:
+      switch (typeName) {
+        default:
+          return null;
+      }
   }
 }
 

diff --git a/packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap b/packages/core/src/config/__tests__/__snapshots__/config-resolvers.test.ts.snap
@@ -211,6 +211,9 @@ exports[`resolveConfig should ignore minimal from the root and read local file 1
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },
+  "overlay1Decorators": {},
+  "overlay1Preprocessors": {},
+  "overlay1Rules": {},
   "preprocessors": {},
   "recommendedFallback": false,
   "rules": {
@@ -437,6 +440,9 @@ exports[`resolveStyleguideConfig should resolve extends with local file config w
     "tag-description": "warn",
     "tags-alphabetical": "off",
   },
+  "overlay1Decorators": {},
+  "overlay1Preprocessors": {},
+  "overlay1Rules": {},
   "preprocessors": {},
   "recommendedFallback": undefined,
   "rules": {

diff --git a/packages/core/src/config/__tests__/__snapshots__/config.test.ts.snap b/packages/core/src/config/__tests__/__snapshots__/config.test.ts.snap
@@ -32,6 +32,11 @@ StyleguideConfig {
       "oas3_0": {},
       "oas3_1": {},
     },
+    "overlay1": {
+      "oas2": {},
+      "oas3_0": {},
+      "oas3_1": {},
+    },
   },
   "doNotResolveExamples": false,
   "extendPaths": [],
@@ -76,6 +81,11 @@ StyleguideConfig {
       "oas3_0": {},
       "oas3_1": {},
     },
+    "overlay1": {
+      "oas2": {},
+      "oas3_0": {},
+      "oas3_1": {},
+    },
   },
   "rawConfig": {
     "_usedRules": Set {},
@@ -203,6 +213,20 @@ StyleguideConfig {
         "operation-summary": "error",
       },
     },
+    "overlay1": {
+      "oas2": {
+        "no-empty-servers": "error",
+        "operation-summary": "error",
+      },
+      "oas3_0": {
+        "no-empty-servers": "error",
+        "operation-summary": "error",
+      },
+      "oas3_1": {
+        "no-empty-servers": "error",
+        "operation-summary": "error",
+      },
+    },
   },
 }
 `;
diff --git a/packages/core/src/config/__tests__/config.test.ts b/packages/core/src/config/__tests__/config.test.ts
@@ -123,6 +123,7 @@ describe('getMergedConfig', () => {
             "oas2": {},
             "oas3_0": {},
             "oas3_1": {},
+            "overlay1": {},
           },
           "doNotResolveExamples": false,
           "extendPaths": [],
@@ -136,6 +137,7 @@ describe('getMergedConfig', () => {
             "oas2": {},
             "oas3_0": {},
             "oas3_1": {},
+            "overlay1": {},
           },
           "rawConfig": {
             "extendPaths": [],
@@ -164,6 +166,9 @@ describe('getMergedConfig', () => {
             "oas3_1": {
               "operation-summary": "warn",
             },
+            "overlay1": {
+              "operation-summary": "warn",
+            },
           },
         },
         "telemetry": "on",
@@ -238,6 +243,7 @@ describe('getMergedConfig', () => {
             "oas2": {},
             "oas3_0": {},
             "oas3_1": {},
+            "overlay1": {},
           },
           "doNotResolveExamples": false,
           "extendPaths": [],
@@ -251,6 +257,7 @@ describe('getMergedConfig', () => {
             "oas2": {},
             "oas3_0": {},
             "oas3_1": {},
+            "overlay1": {},
           },
           "rawConfig": {
             "extendPaths": [],
@@ -287,6 +294,10 @@ describe('getMergedConfig', () => {
               "no-empty-servers": "error",
               "operation-summary": "error",
             },
+            "overlay1": {
+              "no-empty-servers": "error",
+              "operation-summary": "error",
+            },
           },
         },
         "telemetry": "on",

diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
@@ -14,6 +14,7 @@ import type {
   Async2RuleSet,
   Async3RuleSet,
   Arazzo1RuleSet,
+  Overlay1RuleSet,
 } from '../oas-types';
 import type { NodeType } from '../types';
 import type {
@@ -75,6 +76,7 @@ export class StyleguideConfig {
       'async2Rules',
       'async3Rules',
       'arazzo1Rules',
+      'overlay1Rules',
     ];
 
     replaceSpecWithStruct(ruleGroups, rawConfig);
@@ -86,6 +88,7 @@ export class StyleguideConfig {
       [SpecVersion.Async2]: { ...rawConfig.rules, ...rawConfig.async2Rules },
       [SpecVersion.Async3]: { ...rawConfig.rules, ...rawConfig.async3Rules },
       [SpecVersion.Arazzo1]: { ...rawConfig.rules, ...rawConfig.arazzo1Rules },
+      [SpecVersion.Overlay1]: { ...rawConfig.rules, ...rawConfig.overlay1Rules },
     };
 
     this.preprocessors = {
@@ -95,6 +98,7 @@ export class StyleguideConfig {
       [SpecVersion.Async2]: { ...rawConfig.preprocessors, ...rawConfig.async2Preprocessors },
       [SpecVersion.Async3]: { ...rawConfig.preprocessors, ...rawConfig.async3Preprocessors },
       [SpecVersion.Arazzo1]: { ...rawConfig.arazzo1Preprocessors },
+      [SpecVersion.Overlay1]: { ...rawConfig.preprocessors, ...rawConfig.overlay1Preprocessors },
     };
 
     this.decorators = {
@@ -104,6 +108,7 @@ export class StyleguideConfig {
       [SpecVersion.Async2]: { ...rawConfig.decorators, ...rawConfig.async2Decorators },
       [SpecVersion.Async3]: { ...rawConfig.decorators, ...rawConfig.async3Decorators },
       [SpecVersion.Arazzo1]: { ...rawConfig.arazzo1Decorators },
+      [SpecVersion.Overlay1]: { ...rawConfig.decorators, ...rawConfig.overlay1Decorators },
     };
 
     this.extendPaths = rawConfig.extendPaths || [];
@@ -207,6 +212,10 @@ export class StyleguideConfig {
             if (!plugin.typeExtension.arazzo1) continue;
             extendedTypes = plugin.typeExtension.arazzo1(extendedTypes, version);
             break;
+          case SpecVersion.Overlay1:
+            if (!plugin.typeExtension.overlay1) continue;
+            extendedTypes = plugin.typeExtension.overlay1(extendedTypes, version);
+            break;
           default:
             throw new Error('Not implemented');
         }
@@ -328,6 +337,17 @@ export class StyleguideConfig {
           (p) => p.decorators?.arazzo1 && arazzo1Rules.push(p.decorators.arazzo1)
         );
         return arazzo1Rules;
+      case SpecMajorVersion.Overlay1:
+        // eslint-disable-next-line no-case-declarations
+        const overlay1Rules: Overlay1RuleSet[] = [];
+        this.plugins.forEach(
+          (p) => p.preprocessors?.overlay1 && overlay1Rules.push(p.preprocessors.overlay1)
+        );
+        this.plugins.forEach((p) => p.rules?.overlay1 && overlay1Rules.push(p.rules.overlay1));
+        this.plugins.forEach(
+          (p) => p.decorators?.overlay1 && overlay1Rules.push(p.decorators.overlay1)
+        );
+        return overlay1Rules;
     }
   }
 

diff --git a/packages/core/src/config/rules.ts b/packages/core/src/config/rules.ts
@@ -6,6 +6,7 @@ import type {
   Async3RuleSet,
   Oas2RuleSet,
   Oas3RuleSet,
+  Overlay1RuleSet,
   SpecVersion,
 } from '../oas-types';
 import type { StyleguideConfig } from './config';
@@ -18,7 +19,14 @@ type InitializedRule = {
 };
 
 export function initRules(
-  rules: (Oas3RuleSet | Oas2RuleSet | Async2RuleSet | Async3RuleSet | Arazzo1RuleSet)[],
+  rules: (
+    | Oas3RuleSet
+    | Oas2RuleSet
+    | Async2RuleSet
+    | Async3RuleSet
+    | Arazzo1RuleSet
+    | Overlay1RuleSet
+  )[],
   config: StyleguideConfig,
   type: 'rules' | 'preprocessors' | 'decorators',
   oasVersion: SpecVersion

diff --git a/packages/core/src/config/types.ts b/packages/core/src/config/types.ts
@@ -19,6 +19,9 @@ import type {
   Arazzo1PreprocessorsSet,
   Arazzo1DecoratorsSet,
   RuleMap,
+  Overlay1PreprocessorsSet,
+  Overlay1DecoratorsSet,
+  Overlay1RuleSet,
 } from '../oas-types';
 import type { NodeType } from '../types';
 import type { SkipFunctionContext } from '../visitors';
@@ -53,6 +56,7 @@ export type StyleguideRawConfig<T = undefined> = {
   async2Rules?: RuleMap<string, RuleConfig, T>;
   async3Rules?: RuleMap<string, RuleConfig, T>;
   arazzo1Rules?: RuleMap<string, RuleConfig, T>;
+  overlay1Rules?: RuleMap<string, RuleConfig, T>;
 
   preprocessors?: Record<string, PreprocessorConfig>;
   oas2Preprocessors?: Record<string, PreprocessorConfig>;
@@ -61,6 +65,7 @@ export type StyleguideRawConfig<T = undefined> = {
   async2Preprocessors?: Record<string, PreprocessorConfig>;
   async3Preprocessors?: Record<string, PreprocessorConfig>;
   arazzo1Preprocessors?: Record<string, PreprocessorConfig>;
+  overlay1Preprocessors?: Record<string, PreprocessorConfig>;
 
   decorators?: Record<string, DecoratorConfig>;
   oas2Decorators?: Record<string, DecoratorConfig>;
@@ -69,6 +74,7 @@ export type StyleguideRawConfig<T = undefined> = {
   async2Decorators?: Record<string, DecoratorConfig>;
   async3Decorators?: Record<string, DecoratorConfig>;
   arazzo1Decorators?: Record<string, DecoratorConfig>;
+  overlay1Decorators?: Record<string, DecoratorConfig>;
 };
 
 export type ApiStyleguideRawConfig = Omit<StyleguideRawConfig, 'plugins'>;
@@ -87,6 +93,7 @@ export type PreprocessorsConfig = {
   async2?: Async2PreprocessorsSet;
   async3?: Async3PreprocessorsSet;
   arazzo1?: Arazzo1PreprocessorsSet;
+  overlay1?: Overlay1PreprocessorsSet;
 };
 
 export type DecoratorsConfig = {
@@ -95,6 +102,7 @@ export type DecoratorsConfig = {
   async2?: Async2DecoratorsSet;
   async3?: Async3DecoratorsSet;
   arazzo1?: Arazzo1DecoratorsSet;
+  overlay1?: Overlay1DecoratorsSet;
 };
 
 export type TypesExtensionFn = (
@@ -110,6 +118,7 @@ export type RulesConfig<T> = {
   async2?: Async2RuleSet<T>;
   async3?: Async3RuleSet<T>;
   arazzo1?: Arazzo1RuleSet<T>;
+  overlay1?: Overlay1RuleSet<T>;
 };
 
 export type CustomRulesConfig = RulesConfig<undefined>;
@@ -278,17 +287,20 @@ export type RulesFields =
   | 'async2Rules'
   | 'async3Rules'
   | 'arazzo1Rules'
+  | 'overlay1Rules'
   | 'preprocessors'
   | 'oas2Preprocessors'
   | 'oas3_0Preprocessors'
   | 'oas3_1Preprocessors'
   | 'async2Preprocessors'
   | 'async3Preprocessors'
   | 'arazzo1Preprocessors'
+  | 'overlay1Preprocessors'
   | 'decorators'
   | 'oas2Decorators'
   | 'oas3_0Decorators'
   | 'oas3_1Decorators'
   | 'async2Decorators'
   | 'async3Decorators'
-  | 'arazzo1Decorators';
+  | 'arazzo1Decorators'
+  | 'overlay1Decorators';