enhances example(s) removal for api requests

cdimascio · cdimascio · commit 6023756ae972 · 2025-03-02T17:17:05.000-05:00
diff --git a/src/middlewares/parsers/schema.preprocessor.ts b/src/middlewares/parsers/schema.preprocessor.ts
@@ -44,16 +44,24 @@ class Node<T, P> {
 }
 type SchemaObjectNode = Node<SchemaObject, SchemaObject>;
 
-function isParameterObject(node: ParameterObject | ReferenceObject): node is ParameterObject {
-  return !((node as ReferenceObject).$ref);
+function isParameterObject(
+  node: ParameterObject | ReferenceObject,
+): node is ParameterObject {
+  return !(node as ReferenceObject).$ref;
 }
-function isReferenceObject(node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject): node is ReferenceObject {
-  return !!((node as ReferenceObject).$ref);
+function isReferenceObject(
+  node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject,
+): node is ReferenceObject {
+  return !!(node as ReferenceObject).$ref;
 }
-function isArraySchemaObject(node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject): node is ArraySchemaObject {
-  return !!((node as ArraySchemaObject).items);
+function isArraySchemaObject(
+  node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject,
+): node is ArraySchemaObject {
+  return !!(node as ArraySchemaObject).items;
 }
-function isNonArraySchemaObject(node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject): node is NonArraySchemaObject {
+function isNonArraySchemaObject(
+  node: ArraySchemaObject | NonArraySchemaObject | ReferenceObject,
+): node is NonArraySchemaObject {
   return !isArraySchemaObject(node) && !isReferenceObject(node);
 }
 
@@ -119,6 +127,10 @@ export class SchemaPreprocessor {
     // Now that we've processed paths, clone a response spec if we are validating responses
     this.apiDocRes = !!this.responseOpts ? cloneDeep(this.apiDoc) : null;
 
+    if (this.apiDoc.components) {
+      this.removeExamples(this.apiDoc.components);
+    }
+
     const schemaNodes = {
       schemas: componentSchemas,
       requestBodies: r?.requestBodies,
@@ -163,7 +175,7 @@ export class SchemaPreprocessor {
       // Since OpenAPI 3.1, paths can be a #ref to reusable path items
       // The following line mutates the paths item to dereference the reference, so that we can process as a POJO, as we would if it wasn't a reference
       this.apiDoc.paths[p] = pathItem;
-      
+
       for (const method of Object.keys(pathItem)) {
         if (httpMethods.has(method)) {
           const operation = <OpenAPIV3.OperationObject>pathItem[method];
@@ -173,7 +185,8 @@ export class SchemaPreprocessor {
           const node = new Root<OpenAPIV3.OperationObject>(operation, path);
           const requestBodies = this.extractRequestBodySchemaNodes(node);
           const responseBodies = this.extractResponseSchemaNodes(node);
-          const requestParameters = this.extractRequestParameterSchemaNodes(node);
+          const requestParameters =
+            this.extractRequestParameterSchemaNodes(node);
 
           requestBodySchemas.push(...requestBodies);
           responseSchemas.push(...responseBodies);
@@ -246,7 +259,10 @@ export class SchemaPreprocessor {
           recurse(node, child, opts);
         });
       } else if (schema.additionalProperties) {
-        const child = new Node(node, schema.additionalProperties, [...node.path, 'additionalProperties']);
+        const child = new Node(node, schema.additionalProperties, [
+          ...node.path,
+          'additionalProperties',
+        ]);
         recurse(node, child, opts);
       }
     };
@@ -302,7 +318,7 @@ export class SchemaPreprocessor {
         this.handleReadonly(pschema, nschema, options);
         this.handleWriteonly(pschema, nschema, options);
         this.processDiscriminator(pschema, nschema, options);
-        this.removeExamples(pschema, nschema, options)
+        this.removeSchemaExamples(pschema, nschema, options);
       }
     }
   }
@@ -458,21 +474,23 @@ export class SchemaPreprocessor {
     }
   }
 
-  private removeExamples(
+  private removeSchemaExamples(
     parent: OpenAPIV3.SchemaObject,
     schema: OpenAPIV3.SchemaObject,
     opts,
   ) {
-    // Remove example and examples from all schema types, not just objects
-    if (schema?.example) {
-      delete schema.example;
-    }
-    if (schema?.examples) {
-      delete schema.examples;
-    }
+    this.removeExamples(parent);
+    this.removeExamples(schema);
+  }
+
+  private removeExamples(
+    object: OpenAPIV3.SchemaObject | OpenAPIV3.MediaTypeObject,
+  ): void {
+    delete object?.example;
+    delete object?.examples;
   }
 
-private handleReadonly(
+  private handleReadonly(
     parent: OpenAPIV3.SchemaObject,
     schema: OpenAPIV3.SchemaObject,
     opts,
@@ -536,6 +554,10 @@ private handleReadonly(
         mediaTypeObject.schema,
       );
       op.requestBody.content[type].schema = mediaTypeSchema;
+
+      // TODO replace with visitor
+      this.removeExamples(op.requestBody.content[type]);
+
       const path = [...node.path, 'requestBody', 'content', type, 'schema'];
       result.push(new Root(mediaTypeSchema, path));
     }
@@ -575,6 +597,10 @@ private handleReadonly(
               type,
               'schema',
             ];
+
+            // TODO replace with visitor
+            this.removeExamples(rschema.content[type]);
+
             schemas.push(new Root(schema, path));
           }
         }
@@ -586,21 +612,25 @@ private handleReadonly(
   private extractRequestParameterSchemaNodes(
     operationNode: Root<OperationObject>,
   ): Root<SchemaObject>[] {
-
     return (operationNode.schema.parameters ?? []).flatMap((node) => {
       const parameterObject = isParameterObject(node) ? node : undefined;
+
+      // TODO replace with visitor
+      // TODO This does not handle JSON query parameters
+      this.removeExamples(parameterObject);
+
       if (!parameterObject?.schema) return [];
 
-      const schema = isNonArraySchemaObject(parameterObject.schema) ?
-        parameterObject.schema :
-        undefined;
+      const schema = isNonArraySchemaObject(parameterObject.schema)
+        ? parameterObject.schema
+        : undefined;
       if (!schema) return [];
 
       return new Root(schema, [
         ...operationNode.path,
         'parameters',
         parameterObject.name,
-        parameterObject.in
+        parameterObject.in,
       ]);
     });
   }
diff --git a/test/example.removal.spec.ts b/test/example.removal.spec.ts
@@ -0,0 +1,118 @@
+import { expect } from 'chai';
+import * as cloneDeep from 'lodash.clonedeep';
+import * as path from 'path';
+import { AjvOptions } from '../src/framework/ajv/options';
+import { OpenApiSpecLoader } from '../src/framework/openapi.spec.loader';
+import { NormalizedOpenApiValidatorOpts, OpenAPIV3 } from '../src/framework/types';
+import { SchemaPreprocessor } from '../src/middlewares/parsers/schema.preprocessor';
+
+describe('SchemaPreprocessor example removal', () => {
+  let originalApiDoc: any;
+  let ajvOptions: AjvOptions;
+
+
+  before(async () => {
+    const apiSpecPath = path.join('test', 'resources', 'openapi.yaml');
+    const options: NormalizedOpenApiValidatorOpts = {
+      apiSpec: apiSpecPath,
+      validateApiSpec: true,
+      validateResponses: false,
+      validateRequests: {},
+      validateSecurity: false,
+      fileUploader: true,
+      $refParser: {
+        mode: 'bundle',
+      },
+      operationHandlers: false,
+      formats: {},
+      validateFormats: true,
+      // unknownFormats?: never;
+      serDes: [],
+    };
+    // const oav = new OpenApiValidator(options);
+    const spec = await new OpenApiSpecLoader({
+      apiDoc: cloneDeep(options.apiSpec),
+      validateApiSpec: options.validateApiSpec,
+      $refParser: options.$refParser,
+    }).load();
+
+    ajvOptions = new AjvOptions(options);
+    originalApiDoc = spec.apiDoc
+  });
+
+  it('should remove example properties from the GET /pets API request document', () => {
+    // Create preprocessor instance
+    const preprocessor = new SchemaPreprocessor(
+      originalApiDoc,
+      ajvOptions.preprocessor,
+      ajvOptions.response,
+    );
+
+    // Run the preProcess method
+    const result = preprocessor.preProcess();
+
+    // Check that examples were removed from parameters
+    const paths = result.apiDoc.paths;
+    const petsParams = paths?.['/pets']?.get
+      ?.parameters as OpenAPIV3.ParameterObject[];
+    const limitParam = petsParams.find(
+      (p) => (p as OpenAPIV3.ParameterObject).name === 'limit',
+    )!;
+    expect(limitParam.schema).to.not.have.property('example');
+    expect(limitParam).to.not.have.property('example');
+
+    // TODO: Check that examples were removed from request body content
+    // TODO: Fails because JSON query parameter example removal is not yet supported
+    // const testJsonParam = petsParams.find((p) => p.name === 'testJson');
+    // expect(testJsonParam?.content!['application/json']).to.not.have.property(
+    //   'example',
+    // );
+
+    // Check that examples were removed from response content
+    const petsResponse = paths?.['/pets']?.get?.responses?.[
+      '200'
+    ]! as OpenAPIV3.ResponseObject;
+    expect(petsResponse.content!['application/json']).to.not.have.property(
+      'example',
+    );
+    expect(
+      petsResponse.content!['application/json'].schema,
+    ).to.not.have.property('example');
+  });
+
+
+  it('should remove example properties from the GET /pets API response document', () => {
+    // Create preprocessor instance
+    const preprocessor = new SchemaPreprocessor(
+      originalApiDoc,
+      ajvOptions.preprocessor,
+      ajvOptions.response,
+    );
+
+    // Run the preProcess method
+    const result = preprocessor.preProcess();
+
+    const petsGet = result.apiDoc.paths!['/pets'].get!;
+    const petsGetRes = petsGet?.responses!
+    const entries = Object.entries(petsGetRes);
+    entries.forEach(([key, value]) => {
+      const contentMediaTypes = (value! as OpenAPIV3.ResponseObject).content!;
+      const content = contentMediaTypes['application/json'];
+      expect(content).to.not.have.property('example');
+      expect(content.schema).to.not.have.property('example');
+    });
+  });
+
+  it('should remove example properties components:', () => {
+    const preprocessor = new SchemaPreprocessor(
+      originalApiDoc,
+      ajvOptions.preprocessor,
+      ajvOptions.response,
+    );
+
+    const result = preprocessor.preProcess();
+
+    const components = result.apiDoc.components
+    expect(components).to.not.have.property('examples');
+  });
+});
diff --git a/test/resources/openapi.yaml b/test/resources/openapi.yaml
@@ -59,6 +59,8 @@ paths:
             type: integer
             format: int32
             minimum: 5
+            example: 8
+          example: 8
         - name: test
           in: query
           description: maximum number of results to return
@@ -81,6 +83,7 @@ paths:
                     enum:
                       - bar
                       - baz
+              example: {}
         - name: testArrayNoExplode
           in: query
           description: Array in query param
@@ -123,14 +126,21 @@ paths:
             application/json:
               schema:
                 type: array
+                example: 
+                  - {}
                 items:
                   $ref: '#/components/schemas/Pet'
+              example: {}
         default:
           description: unexpected error
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              examples:
+                jsonObject:
+                  summary: A sample object
+                  externalValue: "http://example.com/examples/object-example.json"
     post:
       description: Creates a new pet in the store.  Duplicates are allowed
       operationId: addPet
@@ -397,6 +407,12 @@ paths:
                 $ref: '#/components/schemas/Error'
 
 components:
+  examples: 
+    objectExample:
+      value:
+        id: 1
+        name: new object
+      summary: A sample object
   parameters:
     $ref: 'xt.openapi.parameters.yaml#/parameters'
 
