feat: add support for 'x-query' operation in PathItem type (#2501)

* feat: add support for 'x-query' operation in PathItem type

* tests: add tests for bundling external refs in x-query operations

* feat: changeset

* Update .changeset/fair-moons-knock.md

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

---------

Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>
Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

Author: 3 people

.changeset/fair-moons-knock.md

@@ -0,0 +1,5 @@
+---
+"@redocly/openapi-core": patch
+---
+
+Allowed `x-query` operations names in OpenAPI 3.0 and 3.1 similar to `query` in OpenAPI 3.2.

packages/core/src/__tests__/bundle.test.ts

@@ -67,6 +67,22 @@ describe('bundle', () => {
     expect(res.parsed).toMatchSnapshot();
   });
 
+  it('should bundle external refs under x-query operation (no dereference)', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/refs/openapi-with-external-refs-x-query.yaml'),
+    });
+
+    expect(problems).toHaveLength(0);
+    const parsed = res.parsed as any;
+    expect(
+      parsed.paths['/pet']['x-query'].responses['200'].content['application/json'].schema
+    ).toMatchObject({
+      $ref: '#/components/schemas/schema-a',
+    });
+    expect(parsed.components.schemas['schema-a']).toEqual({ type: 'string' });
+  });
+
   it('should bundle external refs and warn for conflicting names', async () => {
     const { bundle: res, problems } = await bundle({
       config: await createConfig({}),
@@ -92,6 +108,22 @@ describe('bundle', () => {
     expect(res.parsed).toMatchSnapshot();
   });
 
+  it('should dereference external refs under x-query operation when dereference is enabled', async () => {
+    const { bundle: res, problems } = await bundle({
+      config: await createConfig({}),
+      ref: path.join(__dirname, 'fixtures/refs/openapi-with-external-refs-x-query.yaml'),
+      dereference: true,
+    });
+
+    expect(problems).toHaveLength(0);
+    const parsed = res.parsed as any;
+    expect(
+      parsed.paths['/pet']['x-query'].responses['200'].content['application/json'].schema
+    ).toEqual({
+      type: 'string',
+    });
+  });
+
   it('should place referenced schema inline when referenced schema name resolves to original schema name', async () => {
     const { bundle: res, problems } = await bundle({
       config: await createConfig({}),

packages/core/src/__tests__/fixtures/refs/openapi-with-external-refs-x-query.yaml

@@ -0,0 +1,14 @@
+openapi: 3.0.0
+info:
+  title: x-query external refs
+  version: '1.0'
+paths:
+  /pet:
+    x-query:
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: ./schema-a.yaml

packages/core/src/types/oas3.ts

@@ -146,6 +146,7 @@ const PathItem: NodeType = {
     head: 'Operation',
     patch: 'Operation',
     trace: 'Operation',
+    'x-query': 'Operation',
   },
   extensionsPrefix: 'x-',
 };