fix: Remove all OpenAPI examples from spec before validating

[max-at-silverflow]

This PR was made to resolve issue #931. It introduces the following changes:

Commit 189d624:

• Add a stripExamples function that takes an OpenAPIV3.DocumentV3 or OpenAPIV3.DocumentV3_1, removing all example and examples properties. (Note: This only affects examples provided as part of the spec, not user-defined properties called example or examples).
• Call stripExamples in the spec loader to ensure examples are always discarded and do not affect validation in any way.
• Add minimal test setup that verifies this works. (Note: If you remove the stripExamples call, this test fails).

These changes are necessary to avoid the validator from erroring out when providing specs that include multiple examples with the same value for a property id. This is explained in more detail in issue #931, though the proposed solution does not cover all cases. This PR expands on the suggestions and strips all examples, instead of just the component examples.

Note:
Originally, this PR also ran prettier -c -w ./ to improve the code style of the repository (49ffda6). But I realized that were way too many changes, so I reverted them in 8dfdb94. Sorry for the back-and-forth.

Closes #931

[max-at-silverflow]

Originally, this PR also ran prettier -c -w ./, but that was a huge amount of changes. I decided to revert that change, in favor of making this PR more maintainable.

If you want, I can create a separate PR to fix prettier!

[cdimascio]

thanks for the PR @max-at-silverflow. currently, schema.preporcessor traverses the schema. as part of this process it attempts to remove examples (the logic is in schemaVisitor which calls removeExamples). given this PR, i suspect that is not actually remove all examples. can this PR be updated to leverage/fix the existing process. Note that the existing process attempts to clean up examples through a single schema traversal. this logic appears to add a second traversal. i'd like to ensure the single pass is maintained for performance.

Pointers regarding the current remove examples logic:

currently, the schema.preprocessor.ts exposes an entry point method preProcess. preProcess ultimately calls traverseSchemas, which provides a visitor (schemaVisitor):

this.traverseSchemas(schemaNodes, (parent, schema, opts) =>
        this.schemaVisitor(parent, schema, opts),
      );

schema visitor is called during the schema walk. This visitor includes a call to removeExamples. ideally, this call path removes all example and examples.

the schemaVisitor calls removeExamples:

e.g.

private schemaVisitor(
    parent: SchemaObjectNode,
    node: SchemaObjectNode,
    opts: TraversalStates,
  ) {
    const pschemas = [parent?.schema];
    const nschemas = [node.schema];
   // ...
     // visit the node in both the request and response schema
    for (let i = 0; i < nschemas.length; i++) {
      // ...
      this.removeExamples(pschema, nschema, options)
      //..

ideally, this PR leverages this call path

[max-at-silverflow]

Hey @cdimascio! Thanks for the response, that makes a lot of sense! I will see that I can implement it in a compatible way!

[cdimascio]

@max-at-silverflow fyi, i pushed the following change which should help with some example(s) removal
see bd9426c and 6023756 now available in v5.4.6

[max-at-silverflow]

Thanks a lot for the changes! This is a great start!

Unfortunately, it does not resolve all my issue yet. In particular, duplicated ids in the components examples still seem to cause issues (as simulated by the ignore.examples.spec.ts test file).

I am currently trying to understand the pre-processor, hoping to improve the example removal even further. I will see if there is a reasonable way to achieve this.

But thanks for your efforts!

[cdimascio]

No problem. Thank for continuing to investigate.

[max-at-silverflow]

Alright, I made quite some progress on a more complete fix, I will update this MR in the next few days!

…

On Mon, 3 Mar 2025 at 13:39, Carmine DiMascio ***@***.***> wrote: No problem. Thank for continuing to investigate. — Reply to this email directly, view it on GitHub <#1040 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BOLD6FVWMBPZNNYJWI7Z2JD2SRERDAVCNFSM6AAAAABVCWP3XOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJUGI2TAMJQHE> . You are receiving this because you were mentioned.Message ID: ***@***.***> [image: cdimascio]*cdimascio* left a comment (cdimascio/express-openapi-validator#1040) <#1040 (comment)> No problem. Thank for continuing to investigate. — Reply to this email directly, view it on GitHub <#1040 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BOLD6FVWMBPZNNYJWI7Z2JD2SRERDAVCNFSM6AAAAABVCWP3XOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJUGI2TAMJQHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[max-at-silverflow]

Okay, I have something. But it is quite a different fix, with lots more implications. So I made a new MR: #1051. I hope that is in your interest!

We can probably close this MR in turn, but maybe have a look at the other approach, whether it is acceptable for you.

[cdimascio]

closing this out given the variety of related fixes delivered.
there is #1051 which contains a fix, but requires more vetting given its size