CLI: convert to OpenAPI 3.2 (#181)

* CLI: convert to OpenAPI 3.2

Author: thim81

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## unreleased
 
+- CLI: convert an OpenAPI 3.0 document to an OpenAPI version 3.2
+- CLI: convert an OpenAPI 3.1 document to an OpenAPI version 3.2
+
 ## [1.28.0] - 2025-09-12
 
 - Overlay: Support "extends" for referencing OpenAPI documents (#176)

bin/__snapshots__/cli.test.js.snap

@@ -10,6 +10,31 @@ OpenAPI-Format CLI settings:
 "
 `;
 
+exports[`openapi-format CLI command should convert 3.1 to OpenAPI 3.2 1`] = `
+"================================================================================
+OpenAPI-Format CLI settings:
+- Input file:		test/yaml-convert-3.1-3.2/input.yaml
+- OAS version converted to: "3.2"
+================================================================================
+
+OpenAPI-Format CLI options:
+|---------------------|-------|
+| sort                | false |
+| keepComments        | false |
+| sortComponentsProps | false |
+| lineWidth           | -1    |
+| bundle              | true  |
+| split               | false |
+| convertTo           | 3.2   |
+| verbose             | 3     |
+|---------------------|-------|
+
+================================================================================
+✅  OpenAPI formatted successfully
+================================================================================
+"
+`;
+
 exports[`openapi-format CLI command should keep the comments for YAML 1`] = `
 "================================================================================
 OpenAPI-Format CLI settings:
@@ -95,7 +120,7 @@ Options:
   --sortComponentsProps                      sort properties within schema components alphabetically (default: false)
   --lineWidth <lineWidth>                    max line width of YAML output (default: -1)
   --rename <oaTitle>                         overwrite the title in the OpenAPI document
-  --convertTo <oaVersion>                    convert the OpenAPI document to OpenAPI version 3.1
+  --convertTo <oaVersion>                    convert the OpenAPI document to OpenAPI version 3.1 or 3.2
   --no-bundle                                don't bundle the local and remote $ref in the OpenAPI document
   --split                                    split the OpenAPI document into a multi-file structure (default: false)
   --json                                     print the file to stdout as JSON
@@ -225,7 +250,7 @@ OpenAPI-Format CLI settings:
 exports[`openapi-format CLI command should use the convert version 1`] = `
 "================================================================================
 OpenAPI-Format CLI settings:
-- Input file:		test/yaml-convert-3.1/input.yaml
+- Input file:		test/yaml-convert-3.0-3.1/input.yaml
 - OAS version converted to: "3.1"
 ================================================================================
 

bin/cli.js

@@ -4,6 +4,7 @@ const openapiFormat = require('../openapi-format');
 const program = require('commander');
 const {infoTable, infoOut, logOut, debugOut} = require('../utils/logging');
 const {stringify} = require('../openapi-format');
+const {resolveConvertTargetVersion} = require('../utils/convert');
 const fs = require('fs');
 const path = require('path');
 
@@ -29,7 +30,7 @@ program
   .option('--sortComponentsProps', 'sort properties within schema components alphabetically', false)
   .option('--lineWidth <lineWidth>', 'max line width of YAML output', -1)
   .option('--rename <oaTitle>', 'overwrite the title in the OpenAPI document')
-  .option('--convertTo <oaVersion>', 'convert the OpenAPI document to OpenAPI version 3.1')
+  .option('--convertTo <oaVersion>', 'convert the OpenAPI document to OpenAPI version 3.1 or 3.2')
   .option('--no-bundle', `don't bundle the local and remote $ref in the OpenAPI document`, false)
   .option('--split', 'split the OpenAPI document into a multi-file structure', false)
   .option('--json', 'print the file to stdout as JSON')
@@ -324,14 +325,12 @@ async function run(oaFile, options) {
     if (resFormat.data) resObj = resFormat.data;
   }
 
-  // Convert the OpenAPI document to OpenAPI 3.1
-  if (
-    (options.convertTo && options.convertTo.toString() === '3.1') ||
-    (options.convertToVersion && options.convertToVersion === 3.1)
-  ) {
+  // Convert the OpenAPI document to a supported OpenAPI version
+  const convertVersionInfo = resolveConvertTargetVersion(options);
+  if (convertVersionInfo) {
     const resVersion = await openapiFormat.openapiConvertVersion(resObj, options);
     if (resVersion.data) resObj = resVersion.data;
-    debugOut(`- OAS version converted to: "${options.convertTo}"`, options.verbose); // LOG - Conversion title
+    debugOut(`- OAS version converted to: "${convertVersionInfo.label}"`, options.verbose); // LOG - Conversion title
   }
 
   // Rename title OpenAPI document

bin/cli.test.js

@@ -381,7 +381,7 @@ describe('openapi-format CLI command', () => {
   });
 
   it('should use the convert version', async () => {
-    const path = `test/yaml-convert-3.1`;
+    const path = `test/yaml-convert-3.0-3.1`;
     const inputFile = `${path}/input.yaml`;
     const outputFile = `${path}/output.yaml`;
     const output = await getLocalFile(outputFile);
@@ -395,6 +395,20 @@ describe('openapi-format CLI command', () => {
     expect(sanitize(result.stderr)).toStrictEqual(sanitize(output));
   });
 
+  it('should convert 3.1 to OpenAPI 3.2', async () => {
+    const path = `test/yaml-convert-3.1-3.2`;
+    const inputFile = `${path}/input.yaml`;
+    const outputFile = `${path}/output.yaml`;
+    const output = await getLocalFile(outputFile);
+
+    let result = await testUtils.cli([inputFile, `--convertTo "3.2"`, `--no-sort`, `-vvv`], '.');
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('formatted successfully');
+    expect(result.stdout).toContain('OAS version converted to: "3.2"');
+    expect(result.stdout).toMatchSnapshot();
+    expect(sanitize(result.stderr)).toStrictEqual(sanitize(output));
+  });
+
   it('should use the sortComponentsProps option', async () => {
     const path = `test/yaml-sort-component-props`;
     const inputFile = `${path}/input.yaml`;

openapi-format.js

@@ -26,7 +26,10 @@ const {
   convertConst,
   convertExclusiveMinimum,
   convertExclusiveMaximum,
-  setInObject
+  setInObject,
+  convertTagDisplayName,
+  convertTagGroups,
+  resolveConvertTargetVersion
 } = require('./utils/convert');
 const {parseFile, writeFile, stringify, detectFormat, parseString, analyzeOpenApi, readFile} = require('./utils/file');
 const {parseTpl, getOperation} = require('./utils/parseTpl');
@@ -1107,7 +1110,15 @@ async function openapiConvertVersion(oaObj, options) {
   // let debugConvertVersionStep = '' // uncomment // debugConvertVersionStep below to see which sort part is triggered
 
   // Change OpenAPI version
-  jsonObj.openapi = '3.1.0';
+  const targetVersionInfo = resolveConvertTargetVersion(options) || {label: '3.1', normalized: '3.1.0'};
+  const targetVersionLabel = targetVersionInfo.label;
+  jsonObj.openapi = targetVersionInfo.normalized;
+
+  const isTargetVersion32 = targetVersionLabel === '3.2';
+
+  if (isTargetVersion32) {
+    jsonObj = convertTagGroups(jsonObj);
+  }
 
   // Change x-webhooks to webhooks
   if (jsonObj['x-webhooks']) {
@@ -1136,6 +1147,10 @@ async function openapiConvertVersion(oaObj, options) {
         // Change type > single enum
         node = convertConst(node);
       }
+
+      if (isTargetVersion32) {
+        node = convertTagDisplayName(node);
+      }
       this.update(node);
 
       // Change components/schemas - schema

readme.md

@@ -14,7 +14,7 @@ Additional features include powerful filtering options based on flags, tags, met
 To quickly standardize OpenAPI documents there is support for generating the operationIds and apply casing rules for consistency.
 
 The CLI can split large OpenAPI documents into modular, multi-file structures for easier management. 
-For upgrades, the openapi-format CLI offers the option to convert an OpenAPI 3.0 document to OpenAPI 3.1.
+For upgrades, the openapi-format CLI offers the option to convert an OpenAPI 3.0 or 3.1 document to OpenAPI 3.1 or 3.2.
 
 With the newly added OpenAPI Overlay support, users can overlay changes onto existing OpenAPI documents, to extend and customize the OpenAPI document.
 
@@ -79,7 +79,8 @@ Postman collections, test suites, ...
 - [x] Generate OpenAPI elements for consistency
 - [x] Bundle local and remote references in the OpenAPI document
 - [x] Split the OpenAPI document into a multi-file structure
-- [x] Convert OpenAPI 3.0 documents to OpenAPI 3.1 
+- [x] Convert OpenAPI 3.0 documents to OpenAPI 3.1 or 3.2
+- [x] Convert OpenAPI 3.1 documents to OpenAPI 3.2
 - [x] Rename the OpenAPI title
 - [x] Support OpenAPI documents in JSON format
 - [x] Support OpenAPI documents in YAML format
@@ -165,7 +166,7 @@ Options:
 
   --rename              Rename the OpenAPI title                              [string]
 
-  --convertTo           convert the OpenAPI document to OpenAPI version 3.1   [string]
+  --convertTo           convert the OpenAPI document to OpenAPI version 3.1 or 3.2   [string]
 
   --configFile          The file with the OpenAPI-format CLI options            [path]
 
@@ -198,7 +199,7 @@ Options:
 | --no-bundle           |               | don't bundle the local and remote $ref in the OpenAPI document              | boolean      | FALSE                      | optional |
 | --split               |               | split the OpenAPI document into a multi-file structure                      | boolean      | FALSE                      | optional |
 | --rename              |               | rename the OpenAPI title                                                    | string       |                            | optional |
-| --convertTo           |               | convert the OpenAPI document to OpenAPI version 3.1                         | string       |                            | optional |
+| --convertTo           |               | convert the OpenAPI document to OpenAPI version 3.1 or 3.2                  | string       |                            | optional |
 | --configFile          | -c            | the file with all the format config options                                 | path to file |                            | optional |
 | --lineWidth           |               | max line width of YAML output                                               | number       | -1 (Infinity)              | optional |
 | --json                |               | prints the file to stdout as JSON                                           |              | FALSE                      | optional |
@@ -1424,15 +1425,16 @@ which results in
 
 > 🏗 BETA NOTICE: This feature is considered BETA since we are investigating the configuration syntax and extra formatting/casing capabilities.
 
-- Format & convert the OpenAPI document to OpenAPI version 3.1
+- Format & convert the OpenAPI document to OpenAPI version 3.1 or 3.2
 
-openapi-format can help you to upgrade your current OpenAPI 3.0.x document to the latest version OpenAPI 3.1.
+openapi-format can help you to upgrade your current OpenAPI 3.0.x document to OpenAPI 3.1 or 3.2.
 
 ```shell
 $ openapi-format openapi.json -o openapi-3.1.json --convertTo "3.1"
+$ openapi-format openapi.json -o openapi-3.2.json --convertTo "3.2"
 ```
 
-which results in all the changes described in the [migration guide from Phil Sturgeon](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
+Using `3.1` results in all the changes described in the [migration guide from Phil Sturgeon](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0), while the `3.2` target aligns with the new capabilities highlighted in [OpenAPI 3.2 is here](https://quobix.com/articles/openapi-3.2/).
 
 **before**
 
@@ -1452,6 +1454,8 @@ which results in all the changes described in the [migration guide from Phil Stu
         "title": "OpenAPI Petstore - OpenAPI",
 ```
 
+When converting to 3.2 the `openapi` field will be set to `3.2.0`, preparing the document for features like hierarchical tags, the `QUERY` HTTP method, and reusable media types introduced in the 3.2 release.
+
 ## CLI configuration usage
 
 The openapi-format CLI supports bundling all options in a single configuration file. This can simplify management, especially for CI/CD pipelines where configurations are stored in version control systems.

test/converting.test.js

@@ -9,14 +9,16 @@ const {
   convertConst,
   convertImageBase64,
   convertMultiPartBinary,
+  convertTagDisplayName,
+  convertTagGroups,
   setInObject
 } = require('../utils/convert');
 const {describe, it, expect} = require('@jest/globals');
 
 describe('openapi-format CLI converting tests', () => {
-  describe('yaml-convert to 3.1', () => {
-    it('yaml-convert-3.1 - should match expected output', async () => {
-      const testName = 'yaml-convert-3.1';
+  describe('yaml-convert 3.0 to 3.1', () => {
+    it('yaml-convert-3.0-3.1 - should match expected output', async () => {
+      const testName = 'yaml-convert-3.0-3.1';
       const {result, input, outputBefore, outputAfter} = await testUtils.loadTest(testName);
       // console.log('result',result)
       expect(result.code).toBe(0);
@@ -25,6 +27,26 @@ describe('openapi-format CLI converting tests', () => {
     });
   });
 
+  describe('yaml-convert 3.0 to 3.2', () => {
+    it('yaml-convert-3.0-3.2 - should match expected output', async () => {
+      const testName = 'yaml-convert-3.0-3.2';
+      const {result, input, outputBefore, outputAfter} = await testUtils.loadTest(testName);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('formatted successfully');
+      expect(outputAfter).toStrictEqual(outputBefore);
+    });
+  });
+
+  describe('yaml-convert 3.1 to 3.2', () => {
+    it('yaml-convert-3.1-3.2 - should match expected output', async () => {
+      const testName = 'yaml-convert-3.1-3.2';
+      const {result, input, outputBefore, outputAfter} = await testUtils.loadTest(testName);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('formatted successfully');
+      expect(outputAfter).toStrictEqual(outputBefore);
+    });
+  });
+
   describe('util-convert', () => {
     it('convertNullable - should convert nullable into a type', async () => {
       const obj = {
@@ -185,6 +207,52 @@ describe('openapi-format CLI converting tests', () => {
       });
     });
 
+    it('convertTagDisplayName - should convert x-displayName to summary', async () => {
+      const tag = {
+        name: 'products',
+        'x-displayName': 'Product APIs',
+        description: 'All product operations'
+      };
+      const res = convertTagDisplayName(tag);
+      expect(res).toStrictEqual({
+        name: 'products',
+        summary: 'Product APIs',
+        description: 'All product operations'
+      });
+    });
+
+    it('convertTagGroups - should convert x-tagGroups to native tag relationships', async () => {
+      const doc = {
+        tags: [
+          {name: 'products'},
+          {name: 'books', description: 'Books operations'},
+          {name: 'cds'}
+        ],
+        'x-tagGroups': [
+          {
+            name: 'Products',
+            description: 'All product operations',
+            tags: ['books', 'cds']
+          }
+        ]
+      };
+
+      const res = convertTagGroups(doc);
+      expect(res['x-tagGroups']).toBeUndefined();
+      const productsTag = res.tags.find(tag => tag.name === 'products');
+      const booksTag = res.tags.find(tag => tag.name === 'books');
+      const cdsTag = res.tags.find(tag => tag.name === 'cds');
+
+      expect(productsTag).toMatchObject({
+        name: 'products',
+        summary: 'Products',
+        description: 'All product operations',
+        kind: 'nav'
+      });
+      expect(booksTag).toMatchObject({name: 'books', parent: 'products', kind: 'nav'});
+      expect(cdsTag).toMatchObject({name: 'cds', parent: 'products', kind: 'nav'});
+    });
+
     it('convertImageBase64 - should convert an image upload with base64 encoding', async () => {
       const obj = {
         schema: {
@@ -264,6 +332,10 @@ describe('openapi-format CLI converting tests', () => {
       expect(resExclusiveMinimum).toStrictEqual(obj);
       const resExclusiveMaximum = convertExclusiveMaximum(obj);
       expect(resExclusiveMaximum).toStrictEqual(obj);
+      const resTagDisplayName = convertTagDisplayName(obj);
+      expect(resTagDisplayName).toStrictEqual(obj);
+      const resTagGroups = convertTagGroups(obj);
+      expect(resTagGroups).toStrictEqual(obj);
     });
   });
 });