fix: improve docs, changeset and tests

Author: vadyvas

.changeset/loud-mails-hang.md

@@ -1,5 +1,6 @@
 ---
 "@redocly/openapi-core": patch
+"@redocly/cli": patch
 ---
 
-Fixed an issue where the content of `$ref`s inside `Examples.value` was erroneously resolved during bundling and linting.
+Fixed an issue where the content of `$ref`s inside example values was erroneously resolved during bundling and linting.

docs/@v2/configuration/reference/resolve.md

@@ -21,7 +21,7 @@ One HTTP header is supported for each URL resolved.
 
 - doNotResolveExamples
 - boolean
-- Set this option to `true` to prevent resolving `$ref` fields in `Example`. This affects both `lint` and `bundle` commands. Resolving `$ref`s in other parts of the API description is unaffected.
+- Set this option to `true` to prevent resolving `$ref` fields in singular `example` properties. This affects both `lint` and `bundle` commands. Resolving `$ref`s in other parts of the API description is unaffected.
 
 ---
 

docs/@v2/configuration/resolve.yaml

@@ -12,7 +12,7 @@ properties:
   doNotResolveExamples:
     type: boolean
     description: >-
-      Set this option to `true` to prevent resolving `$ref` fields in `Example`. 
+      Set this option to `true` to prevent resolving `$ref` fields in singular `example` properties.
       This affects both `lint` and `bundle` commands.
       This does not affect `$ref` resolution in other parts of the API description.
     default: false

packages/core/src/__tests__/bundle-examples-ref-resolution.test.ts

@@ -226,62 +226,4 @@ describe('Bundle Examples $ref Resolution', () => {
       `);
     });
   });
-
-  describe('Edge cases and configuration', () => {
-    it('should work with doNotResolveExamples: true config', async () => {
-      const testDocument = parseYamlToDocument(
-        outdent`
-          openapi: 3.1.0
-          info:
-            title: Test API
-            version: 1.0.0
-          paths:
-            /test:
-              get:
-                responses:
-                  '200':
-                    content:
-                      application/json:
-                        examples:
-                          test-example:
-                            value:
-                              $ref: ./example-data.json
-        `,
-        ''
-      );
-
-      const config = await createConfig({
-        resolve: {
-          doNotResolveExamples: true,
-        },
-      });
-
-      const { bundle: result, problems } = await bundleDocument({
-        document: testDocument,
-        externalRefResolver: new BaseResolver(),
-        config,
-        types: Oas3Types,
-      });
-
-      expect(problems).toHaveLength(0);
-      expect(result.parsed).toMatchInlineSnapshot(`
-        openapi: 3.1.0
-        info:
-          title: Test API
-          version: 1.0.0
-        paths:
-          /test:
-            get:
-              responses:
-                '200':
-                  content:
-                    application/json:
-                      examples:
-                        test-example:
-                          value:
-                            $ref: ./example-data.json
-        components: {}
-      `);
-    });
-  });
 });

packages/core/src/rules/oas3/__tests__/struct/referenceableScalars.test.ts

@@ -69,4 +69,38 @@ describe('Referenceable scalars', () => {
     });
     expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
   });
+
+  it('should not report example value with $ref', async () => {
+    const document = parseYamlToDocument(
+      outdent`
+          openapi: 3.2.0
+          info:
+            title: Test
+            version: '1.0'
+          paths:
+            '/test':
+              get:
+                parameters:
+                  - name: test
+                    schema:
+                      type: object
+                    examples:
+                      test:
+                        value:
+                          $ref: not $ref, example
+        `,
+      __dirname + '/foobar.yaml'
+    );
+
+    const results = await lintDocument({
+      externalRefResolver: new BaseResolver(),
+      document,
+      config: await createConfig({
+        rules: {
+          'no-unresolved-refs': 'error',
+        },
+      }),
+    });
+    expect(replaceSourceWithRef(results)).toMatchInlineSnapshot(`[]`);
+  });
 });