feat: introduce basic OAS3.2 support

Author: tatomyr

docs/@v2/rules/ruleset-templates.md

@@ -257,7 +257,7 @@ The default behavior is to use a recommended ruleset.
 The recommended rulesets for each format are listed below.
 There is also a "recommended-strict" ruleset which is identical but with all `warn` settings changed to `error`.
 
-### Recommended ruleset: OpenAPI 3.1
+### Recommended ruleset: OpenAPI 3.1/3.2
 
 ```yaml
 rules:
@@ -297,6 +297,7 @@ rules:
   required-string-property-missing-min-length: off
   response-contains-header: off
   scalar-property-missing-example: off
+  no-duplicated-tag-names: warn
   no-required-schema-properties-undefined: warn
   no-schema-type-mismatch: error
   no-enum-type-mismatch: error

packages/cli/src/__tests__/commands/join.test.ts

@@ -152,7 +152,7 @@ describe('handleJoin', () => {
       version: 'cli-version',
     });
     expect(exitWithError).toHaveBeenCalledWith(
-      'Only OpenAPI 3.0 and OpenAPI 3.1 are supported: undefined.'
+      'Only OpenAPI 3.0, 3.1, and 3.2 are supported: undefined.'
     );
   });
 

packages/cli/src/__tests__/fixtures/config.ts

@@ -20,6 +20,7 @@ export const configFixture: Config = {
     oas2: {},
     oas3_0: {},
     oas3_1: {},
+    oas3_2: {},
     async2: {},
     async3: {},
     arazzo1: {},
@@ -29,6 +30,7 @@ export const configFixture: Config = {
     oas2: {},
     oas3_0: {},
     oas3_1: {},
+    oas3_2: {},
     async2: {},
     async3: {},
     arazzo1: {},
@@ -40,6 +42,7 @@ export const configFixture: Config = {
     oas2: {},
     oas3_0: {},
     oas3_1: {},
+    oas3_2: {},
     async2: {},
     async3: {},
     arazzo1: {},

packages/cli/src/__tests__/utils.test.ts

@@ -540,6 +540,7 @@ describe('checkIfRulesetExist', () => {
       oas2: {},
       oas3_0: {},
       oas3_1: {},
+      oas3_2: {},
       async2: {},
       async3: {},
       arazzo1: {},

packages/cli/src/commands/join.ts

@@ -33,10 +33,12 @@ import type {
   BundleResult,
   Oas3Definition,
   Oas3_1Definition,
+  Oas3_2Definition,
   Oas3Parameter,
   Oas3PathItem,
   Oas3Server,
   Oas3Tag,
+  Oas3_2Tag,
   SpecVersion,
 } from '@redocly/openapi-core';
 import type { CommandArgs } from '../wrapper.js';
@@ -46,14 +48,17 @@ const Tags = 'tags';
 const xTagGroups = 'x-tagGroups';
 let potentialConflictsTotal = 0;
 
+type AnyOas3Definition = Oas3Definition | Oas3_1Definition | Oas3_2Definition;
+
 type JoinDocumentContext = {
   api: string;
   apiFilename: string;
   apiTitle?: string;
-  tags?: Oas3Tag[];
+  tags?: (Oas3Tag | Oas3_2Tag)[];
   potentialConflicts: any;
   tagsPrefix: string;
   componentsPrefix: string | undefined;
+  oasVersion: Extract<SpecVersion, 'oas3_0' | 'oas3_1' | 'oas3_2'> | null;
 };
 
 export type JoinArgv = {
@@ -154,9 +159,9 @@ export async function handleJoin({
     try {
       const version = detectSpec(document.parsed);
       collectSpecData?.(document.parsed);
-      if (version !== 'oas3_0' && version !== 'oas3_1') {
+      if (version !== 'oas3_0' && version !== 'oas3_1' && version !== 'oas3_2') {
         return exitWithError(
-          `Only OpenAPI 3.0 and OpenAPI 3.1 are supported: ${blue(document.source.absoluteRef)}.`
+          `Only OpenAPI 3.0, 3.1, and 3.2 are supported: ${blue(document.source.absoluteRef)}.`
         );
       }
 
@@ -171,7 +176,7 @@ export async function handleJoin({
     }
   }
 
-  const [first, ...others] = (documents ?? []) as Document<Oas3Definition | Oas3_1Definition>[];
+  const [first, ...others] = (documents ?? []) as Document<AnyOas3Definition>[];
   const serversAreTheSame = others.every(({ parsed: { paths, servers } }) => {
     // include only documents with paths
     if (!paths || isEmptyObject(paths || {})) {
@@ -197,9 +202,9 @@ export async function handleJoin({
   }
 
   for (const document of documents) {
-    const openapi = isPlainObject<Oas3Definition | Oas3_1Definition>(document.parsed)
+    const openapi = isPlainObject<AnyOas3Definition>(document.parsed)
       ? document.parsed
-      : ({} as Oas3Definition | Oas3_1Definition);
+      : ({} as AnyOas3Definition);
     const { tags, info } = openapi;
     const api = path.relative(process.cwd(), document.source.absoluteRef);
     const apiFilename = getApiFilename(api);
@@ -220,14 +225,15 @@ export async function handleJoin({
       potentialConflicts,
       tagsPrefix,
       componentsPrefix,
+      oasVersion,
     };
     if (tags) {
       populateTags(context);
     }
     collectExternalDocs(openapi, context);
     collectPaths(openapi, context, serversAreTheSame);
     collectComponents(openapi, context);
-    collectWebhooks(oasVersion!, openapi, context);
+    collectWebhooks(openapi, context);
     if (componentsPrefix) {
       replace$Refs(openapi, componentsPrefix);
     }
@@ -252,6 +258,7 @@ export async function handleJoin({
     potentialConflicts,
     tagsPrefix,
     componentsPrefix,
+    oasVersion,
   }: JoinDocumentContext) {
     if (!joinedDef.hasOwnProperty(Tags)) {
       joinedDef[Tags] = [];
@@ -268,7 +275,9 @@ export async function handleJoin({
         tag.description = addComponentsPrefix(tag.description, componentsPrefix!);
       }
 
-      const tagDuplicate = joinedDef.tags.find((t: Oas3Tag) => t.name === entrypointTagName);
+      const tagDuplicate = joinedDef.tags.find(
+        (t: Oas3Tag | Oas3_2Tag) => t.name === entrypointTagName
+      );
 
       if (tagDuplicate && withoutXTagGroups) {
         // If tag already exist and `without-x-tag-groups` option,
@@ -281,7 +290,11 @@ export async function handleJoin({
         );
       } else if (!tagDuplicate) {
         // Instead add tag to joinedDef if there no duplicate;
-        tag['x-displayName'] = tag['x-displayName'] || tag.name;
+        if (oasVersion === 'oas3_0' || oasVersion === 'oas3_1') {
+          (tag as Oas3Tag)['x-displayName'] = (tag as Oas3Tag)['x-displayName'] || tag.name;
+        } else if (oasVersion === 'oas3_2') {
+          (tag as Oas3_2Tag).summary = (tag as Oas3_2Tag).summary || tag.name;
+        }
         tag.name = entrypointTagName;
         joinedDef.tags.push(tag);
 
@@ -290,7 +303,7 @@ export async function handleJoin({
         }
       }
 
-      if (!withoutXTagGroups) {
+      if (!withoutXTagGroups && oasVersion !== 'oas3_2') {
         const groupName = apiTitle || apiFilename;
         createXTagGroups(groupName);
         if (!tagDuplicate) {
@@ -337,10 +350,7 @@ export async function handleJoin({
     }
   }
 
-  function collectExternalDocs(
-    openapi: Oas3Definition | Oas3_1Definition,
-    { api }: JoinDocumentContext
-  ) {
+  function collectExternalDocs(openapi: AnyOas3Definition, { api }: JoinDocumentContext) {
     const { externalDocs } = openapi;
     if (externalDocs) {
       if (joinedDef.hasOwnProperty('externalDocs')) {
@@ -352,14 +362,15 @@ export async function handleJoin({
   }
 
   function collectPaths(
-    openapi: Oas3Definition | Oas3_1Definition,
+    openapi: AnyOas3Definition,
     {
       apiFilename,
       apiTitle,
       api,
       potentialConflicts,
       tagsPrefix,
       componentsPrefix,
+      oasVersion,
     }: JoinDocumentContext,
     serversAreTheSame: boolean
   ) {
@@ -521,6 +532,7 @@ export async function handleJoin({
           potentialConflicts,
           tagsPrefix,
           componentsPrefix,
+          oasVersion,
         });
       } else {
         joinedDef.paths[path][operation]['tags'] = [addPrefix('other', tagsPrefix || apiFilename)];
@@ -532,6 +544,7 @@ export async function handleJoin({
           potentialConflicts,
           tagsPrefix: tagsPrefix || apiFilename,
           componentsPrefix,
+          oasVersion,
         });
       }
       if (!security && openapi.hasOwnProperty('security')) {
@@ -557,7 +570,7 @@ export async function handleJoin({
   }
 
   function collectComponents(
-    openapi: Oas3Definition | Oas3_1Definition,
+    openapi: AnyOas3Definition,
     { api, potentialConflicts, componentsPrefix }: JoinDocumentContext
   ) {
     const { components } = openapi;
@@ -583,19 +596,19 @@ export async function handleJoin({
   }
 
   function collectWebhooks(
-    oasVersion: SpecVersion,
-    openapi: Oas3Definition | Oas3_1Definition,
+    openapi: AnyOas3Definition,
     {
       apiFilename,
       apiTitle,
       api,
       potentialConflicts,
       tagsPrefix,
       componentsPrefix,
+      oasVersion,
     }: JoinDocumentContext
   ) {
     const webhooks = oasVersion === 'oas3_1' ? 'webhooks' : 'x-webhooks';
-    const openapiWebhooks = (openapi as Exact<Oas3Definition | Oas3_1Definition>)[webhooks];
+    const openapiWebhooks = (openapi as Exact<AnyOas3Definition>)[webhooks];
     if (openapiWebhooks) {
       if (!joinedDef.hasOwnProperty(webhooks)) {
         joinedDef[webhooks] = {};
@@ -626,6 +639,7 @@ export async function handleJoin({
               potentialConflicts,
               tagsPrefix,
               componentsPrefix,
+              oasVersion,
             });
           }
         }

packages/cli/src/commands/split/index.ts

@@ -27,6 +27,7 @@ import { COMPONENTS, OPENAPI3_METHOD_NAMES, OPENAPI3_COMPONENT_NAMES } from './t
 import type {
   Oas3Definition,
   Oas3_1Definition,
+  Oas3_2Definition,
   Oas2Definition,
   Oas3Schema,
   Oas3_1Schema,
@@ -41,6 +42,8 @@ import type { ComponentsFiles, Definition, Oas3Component, RefObject } from './ty
 import type { CommandArgs } from '../../wrapper.js';
 import type { VerifyConfigOptions } from '../../types.js';
 
+type AnyOas3Definition = Oas3Definition | Oas3_1Definition | Oas3_2Definition;
+
 export type SplitArgv = {
   api: string;
   outDir: string;
@@ -52,7 +55,7 @@ export async function handleSplit({ argv, collectSpecData }: CommandArgs<SplitAr
   const { api, outDir, separator } = argv;
   validateDefinitionFileName(api);
   const ext = getAndValidateFileExtension(api);
-  const openapi = readYaml(api) as Oas3Definition | Oas3_1Definition;
+  const openapi = readYaml(api) as AnyOas3Definition;
   collectSpecData?.(openapi);
   splitDefinition(openapi, outDir, separator, ext);
   logger.info(
@@ -63,7 +66,7 @@ export async function handleSplit({ argv, collectSpecData }: CommandArgs<SplitAr
 }
 
 function splitDefinition(
-  openapi: Oas3Definition | Oas3_1Definition,
+  openapi: AnyOas3Definition,
   openapiDir: string,
   pathSeparator: string,
   ext: string
@@ -82,7 +85,8 @@ function splitDefinition(
     ext
   );
   const webhooks =
-    (openapi as Oas3_1Definition).webhooks || (openapi as Oas3Definition)['x-webhooks'];
+    (openapi as Oas3_1Definition | Oas3_2Definition).webhooks ||
+    (openapi as Oas3Definition)['x-webhooks'];
   // use webhook_ prefix for code samples to prevent potential name-clashes with paths samples
   iteratePathItems(
     webhooks,
@@ -119,7 +123,7 @@ function validateDefinitionFileName(fileName: string) {
   const file = loadFile(fileName);
   if ((file as Oas2Definition).swagger)
     exitWithError('OpenAPI 2 is not supported by this command.');
-  if (!(file as Oas3Definition | Oas3_1Definition).openapi)
+  if (!(file as AnyOas3Definition).openapi)
     exitWithError(
       'File does not conform to the OpenAPI Specification. OpenAPI version is not specified.'
     );
@@ -242,7 +246,7 @@ function doesFileDiffer(filename: string, componentData: any) {
 }
 
 function removeEmptyComponents(
-  openapi: Oas3Definition | Oas3_1Definition,
+  openapi: AnyOas3Definition,
   componentType: Oas3ComponentName<Oas3Schema | Oas3_1Schema>
 ) {
   if (openapi.components && isEmptyObject(openapi.components[componentType])) {
@@ -339,7 +343,7 @@ function iteratePathItems(
 }
 
 function iterateComponents(
-  openapi: Oas3Definition | Oas3_1Definition,
+  openapi: AnyOas3Definition,
   openapiDir: string,
   componentsFiles: ComponentsFiles,
   ext: string

packages/cli/src/commands/split/types.ts

@@ -1,6 +1,11 @@
-import type { Oas2Definition, Oas3_1Definition, Oas3Definition } from '@redocly/openapi-core';
+import type {
+  Oas2Definition,
+  Oas3Definition,
+  Oas3_1Definition,
+  Oas3_2Definition,
+} from '@redocly/openapi-core';
 
-export type Definition = Oas3_1Definition | Oas3Definition | Oas2Definition;
+export type Definition = Oas2Definition | Oas3Definition | Oas3_1Definition | Oas3_2Definition;
 export interface ComponentsFiles {
   [schemas: string]: any;
 }