Sort & Filter OpenAPI 3.2 (#182)

* Sort & Filter OpenAPI 3.2

Author: thim81

CHANGELOG.md

@@ -1,7 +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
+- Sort & Filter: Added support for OpenAPI 3.2 (#182)
+- CLI: convert an OpenAPI 3.0 document to an OpenAPI version 3.2 (#181)
+- CLI: convert an OpenAPI 3.1 document to an OpenAPI version 3.2 (#181)
 
 ## [1.28.0] - 2025-09-12
 

defaultSort.json

@@ -1,6 +1,7 @@
 {
   "root": ["openapi", "info", "servers", "paths", "components", "tags", "x-tagGroups", "externalDocs"],
   "get": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
+  "query": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
   "post": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
   "put": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
   "patch": ["operationId", "summary", "description", "parameters", "requestBody", "responses"],
@@ -9,7 +10,7 @@
   "requestBody": ["description", "required", "content"],
   "responses": ["description", "headers", "content", "links"],
   "content": [],
-  "components": ["parameters", "schemas"],
+  "components": ["parameters", "schemas", "mediaTypes"],
   "schema": ["description", "type", "items", "properties", "format", "example", "default"],
   "schemas": ["description", "type", "items", "properties", "format", "example", "default"],
   "properties": ["description", "type", "items", "format", "example", "default", "enum"]

openapi-format.js

@@ -196,8 +196,9 @@ async function openapiFilter(oaObj, options) {
   let jsonObj = JSON.parse(JSON.stringify(oaObj)); // Deep copy of the schema object
   let defaultFilter = options.defaultFilter || (await parseFile(__dirname + '/defaultFilter.json'));
   let filterSet = Object.assign({}, defaultFilter, options.filterSet);
-  const httpVerbs = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+  const httpVerbs = ['get', 'query', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
   const fixedFlags = ['x-openapi-format-filter'];
+  const componentTypes = ['schemas', 'responses', 'parameters', 'examples', 'requestBodies', 'headers', 'mediaTypes'];
   options.unusedDepth = options.unusedDepth || 0;
 
   // Merge object filters
@@ -232,26 +233,22 @@ async function openapiFilter(oaObj, options) {
   const inverseFilterFlagHash = inverseFilterFlagValues.map(o => JSON.stringify(o));
 
   // Initiate components tracking
-  const comps = {
-    schemas: {},
-    responses: {},
-    parameters: {},
-    examples: {},
-    requestBodies: {},
-    headers: {},
-    meta: {total: 0}
-  };
+  const comps = componentTypes.reduce(
+    (acc, type) => {
+      acc[type] = {};
+      return acc;
+    },
+    {meta: {total: 0}}
+  );
 
   // Prepare unused components
-  let unusedComp = {
-    schemas: [],
-    responses: [],
-    parameters: [],
-    examples: [],
-    requestBodies: [],
-    headers: [],
-    meta: {total: 0}
-  };
+  let unusedComp = componentTypes.reduce(
+    (acc, type) => {
+      acc[type] = [];
+      return acc;
+    },
+    {meta: {total: 0}}
+  );
   // Use options.unusedComp to collect unused components during multiple recursion
   if (!options.unusedComp) options.unusedComp = JSON.parse(JSON.stringify(unusedComp));
 
@@ -268,7 +265,7 @@ async function openapiFilter(oaObj, options) {
 
     // Register components usage
     if (this.key === '$ref' && typeof node === 'string') {
-      for (let type of ['schemas', 'responses', 'parameters', 'examples', 'requestBodies', 'headers']) {
+      for (let type of componentTypes) {
         const prefix = `#/components/${type}/`;
         if (node.startsWith(prefix)) {
           const name = node.slice(prefix.length);
@@ -639,14 +636,14 @@ async function openapiFilter(oaObj, options) {
   const optFs = get(options, 'filterSet.unusedComponents', []) || [];
 
   // Identify components that are directly unused (not referenced anywhere)
-  unusedComp.schemas = Object.keys(comps.schemas || {}).filter(key => !comps.schemas[key].used);
-  unusedComp.responses = Object.keys(comps.responses || {}).filter(key => !comps.responses[key].used);
-  unusedComp.parameters = Object.keys(comps.parameters || {}).filter(key => !comps.parameters[key].used);
-  unusedComp.examples = Object.keys(comps.examples || {}).filter(key => !comps.examples[key].used);
-  unusedComp.requestBodies = Object.keys(comps.requestBodies || {}).filter(key => !comps.requestBodies[key].used);
-  unusedComp.headers = Object.keys(comps.headers || {}).filter(key => !comps.headers[key].used);
-
-  const refGraph = {schemas: {}, responses: {}, parameters: {}, examples: {}, requestBodies: {}, headers: {}};
+  componentTypes.forEach(type => {
+    unusedComp[type] = Object.keys(comps[type] || {}).filter(key => !comps[type][key].used);
+  });
+
+  const refGraph = componentTypes.reduce((acc, type) => {
+    acc[type] = {};
+    return acc;
+  }, {});
   const rootRefs = new Set();
 
   // Traverse $ref in components
@@ -681,42 +678,28 @@ async function openapiFilter(oaObj, options) {
   }
 
   // Mark not visited as unused
-  for (const t of ['schemas', 'responses', 'parameters', 'examples', 'requestBodies', 'headers']) {
+  for (const t of componentTypes) {
     unusedComp[t] = Object.keys(comps[t] || {}).filter(k => !visited.has(`${t}:${k}`));
   }
 
   // TODO rework this logic
   unusedComp.meta = {
-    total:
-      unusedComp.schemas.length +
-      unusedComp.responses.length +
-      unusedComp.parameters.length +
-      unusedComp.examples.length +
-      unusedComp.requestBodies.length +
-      unusedComp.headers.length
+    total: componentTypes.reduce((acc, type) => acc + (unusedComp[type]?.length || 0), 0)
   };
 
   // Update options.unusedComp with all identified unused components
-  if (optFs.includes('schemas')) options.unusedComp.schemas = [...options.unusedComp.schemas, ...unusedComp.schemas];
-  if (optFs.includes('responses'))
-    options.unusedComp.responses = [...options.unusedComp.responses, ...unusedComp.responses];
-  if (optFs.includes('parameters'))
-    options.unusedComp.parameters = [...options.unusedComp.parameters, ...unusedComp.parameters];
-  if (optFs.includes('examples'))
-    options.unusedComp.examples = [...options.unusedComp.examples, ...unusedComp.examples];
-  if (optFs.includes('requestBodies'))
-    options.unusedComp.requestBodies = [...options.unusedComp.requestBodies, ...unusedComp.requestBodies];
-  if (optFs.includes('headers')) options.unusedComp.headers = [...options.unusedComp.headers, ...unusedComp.headers];
+  componentTypes.forEach(type => {
+    if (optFs.includes(type)) {
+      options.unusedComp[type] = [...options.unusedComp[type], ...unusedComp[type]];
+    }
+  });
 
   // TODO rework this logic
   // Update unusedComp.meta.total after each recursion
-  options.unusedComp.meta.total =
-    options.unusedComp.schemas.length +
-    options.unusedComp.responses.length +
-    options.unusedComp.parameters.length +
-    options.unusedComp.examples.length +
-    options.unusedComp.requestBodies.length +
-    options.unusedComp.headers.length;
+  options.unusedComp.meta.total = componentTypes.reduce(
+    (acc, type) => acc + (options.unusedComp[type]?.length || 0),
+    0
+  );
 
   // Clean-up jsonObj
   traverse(jsonObj).forEach(function (node) {
@@ -806,15 +789,13 @@ async function openapiFilter(oaObj, options) {
   }
 
   // Prepare totalComp for the final result
-  const totalComp = {
-    schemas: Object.keys(comps.schemas),
-    responses: Object.keys(comps.responses),
-    parameters: Object.keys(comps.parameters),
-    examples: Object.keys(comps.examples),
-    requestBodies: Object.keys(comps.requestBodies),
-    headers: Object.keys(comps.headers),
-    meta: {total: comps.meta.total}
-  };
+  const totalComp = componentTypes.reduce(
+    (acc, type) => {
+      acc[type] = Object.keys(comps[type]);
+      return acc;
+    },
+    {meta: {total: comps.meta.total}}
+  );
 
   // Return result object
   return {data: jsonObj, resultData: {unusedComp: unusedComp, totalComp: totalComp}};
@@ -1099,7 +1080,7 @@ async function openapiSplit(oaObj, options = {}) {
 
 /**
  * OpenAPI convert version function
- * Convert OpenAPI from version 3.0 to 3.1
+ * Convert OpenAPI from version 3.0 to 3.1 or 3.2
  * @param {object} oaObj OpenAPI document
  * @param {object} options OpenAPI-format convert options
  * @returns {object} converted OpenAPI document

readme.md

@@ -89,7 +89,8 @@ Postman collections, test suites, ...
 - [x] Use as a Module
 - [x] Aligned YAML parsing style with Stoplight Studio style
 - [x] Support for OpenAPI 3.0
-- [x] Support for OpenAPI 3.1 (beta)
+- [x] Support for OpenAPI 3.1
+- [x] Support for OpenAPI 3.2
 - [x] Online playground (https://openapi-format-playground.vercel.app/)
 
 ## Online playground
@@ -395,7 +396,7 @@ Strict matching example: `"GET::/pets"`
 This will target only the "GET" method and the specific path "/pets"
 
 Method wildcard matching example: `"*::/pets"`
-This will target all methods ('get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace') and the specific
+This will target all methods ('get', 'query', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace') and the specific
 path "/pets"
 
 Path wildcard matching example: `"GET::/pets/*"`
@@ -638,6 +639,7 @@ Supported component types that can be marked as "unused":
 - headers
 - requestBodies
 - responses
+- mediaTypes
 
 ### Filter - textReplace
 
@@ -1423,8 +1425,6 @@ which results in
 
 ## CLI convertTo usage
 
-> 🏗 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 or 3.2
 
 openapi-format can help you to upgrade your current OpenAPI 3.0.x document to OpenAPI 3.1 or 3.2.

test/converting.test.js

@@ -223,11 +223,7 @@ describe('openapi-format CLI converting tests', () => {
 
     it('convertTagGroups - should convert x-tagGroups to native tag relationships', async () => {
       const doc = {
-        tags: [
-          {name: 'products'},
-          {name: 'books', description: 'Books operations'},
-          {name: 'cds'}
-        ],
+        tags: [{name: 'products'}, {name: 'books', description: 'Books operations'}, {name: 'cds'}],
         'x-tagGroups': [
           {
             name: 'Products',

test/filtering.test.js

@@ -136,6 +136,26 @@ describe('openapi-format CLI filtering tests', () => {
     });
   });
 
+  describe('yaml-filter-query-operations', () => {
+    it('yaml-filter-query-operations - should match expected output', async () => {
+      const testName = 'yaml-filter-query-operations';
+      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-filter-query-methods', () => {
+    it('yaml-filter-query-methods - should match expected output', async () => {
+      const testName = 'yaml-filter-query-methods';
+      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-filter-custom-tags', () => {
     it('yaml-filter-custom-tags - should match expected output', async () => {
       const testName = 'yaml-filter-custom-tags';
@@ -246,6 +266,16 @@ describe('openapi-format CLI filtering tests', () => {
     });
   });
 
+  describe('yaml-filter-unused-components-mediatypes', () => {
+    it('yaml-filter-unused-components-mediatypes - should match expected output', async () => {
+      const testName = 'yaml-filter-unused-components-mediatypes';
+      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-strip-flags', () => {
     it('yaml-strip-flags - should match expected output', async () => {
       const testName = 'yaml-strip-flags';

test/sorting.test.js

@@ -203,6 +203,16 @@ describe('openapi-format CLI sorting tests', () => {
     });
   });
 
+  describe('yaml-sort-query', () => {
+    it('yaml-sort-query - should match expected output', async () => {
+      const testName = 'yaml-sort-query';
+      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-sort-paths', () => {
     it('yaml-sort-paths by alphabet - should match expected output', async () => {
       const testName = 'yaml-sort-paths-alphabet';
@@ -240,6 +250,16 @@ describe('openapi-format CLI sorting tests', () => {
       expect(res).toEqual(false);
     });
 
+    it('isMatchOperationItem - should support QUERY operations', () => {
+      const res = isMatchOperationItem('/items', 'query', 'QUERY::/items');
+      expect(res).toEqual(true);
+    });
+
+    it('isMatchOperationItem - wildcard should match QUERY operations', () => {
+      const res = isMatchOperationItem('/items', 'query', '*::/items');
+      expect(res).toEqual(true);
+    });
+
     it('arraySort - should sort an array of objects in ascending order', () => {
       const inputArray = [
         {

test/util-file.test.js

@@ -266,17 +266,11 @@ describe('openapi-format CLI file tests', () => {
     const invalidRemoteFileHttp = 'http://google.com/nonexistent-file.txt';
     const invalidRemoteFileHttps = 'https://google.com/nonexistent-file.txt';
 
-    test('should download remote file content successfully', async () => {
-      const content = await getRemoteFile(validRemoteFilePath);
-      const fileContent = fs.readFileSync(validFilePath, 'utf8');
-      expect(content).toEqual(fileContent);
-    });
-
-    test('should download remote file content successfully', async () => {
-      const content = await getRemoteFile(validRemoteFilePath);
-      const fileContent = fs.readFileSync(validFilePath, 'utf8');
-      expect(content).toEqual(fileContent);
-    });
+    // test('should download remote file content successfully', async () => {
+    //   const content = await getRemoteFile(validRemoteFilePath);
+    //   const fileContent = fs.readFileSync(validFilePath, 'utf8');
+    //   expect(content).toEqual(fileContent);
+    // });
 
     test('should throw an error for https nonexistent remote file', async () => {
       try {

test/yaml-filter-query-methods/input.yaml

@@ -0,0 +1,36 @@
+openapi: 3.2.0
+info:
+  title: Query operations filtering
+  version: 1.0.0
+paths:
+  /items:
+    query:
+      summary: Query items
+      description: Search items with a request body
+      operationId: queryItems
+      responses:
+        '200':
+          description: Successful query
+    get:
+      summary: List items
+      operationId: listItems
+      responses:
+        '200':
+          description: Successful retrieval
+  /search:
+    query:
+      summary: Search catalogue
+      operationId: searchItems
+      responses:
+        '200':
+          description: Search response
+components:
+  mediaTypes:
+    CollectionJson:
+      schema:
+        type: object
+        properties:
+          items:
+            type: array
+            items:
+              type: string

test/yaml-filter-query-methods/options.yaml

@@ -0,0 +1,5 @@
+verbose: true
+output: output.yaml
+filterSet:
+  methods:
+    - QUERY