fix: nested examples in OpenAPI schemas for request body & response

[shfrmn]

Summary

Fixes #771

This PR addresses the following issue — example values in nested schemas of request body and response are not getting transformed into OpenAPI compliant format. For example, fastify schema below is not being processed correctly. Specifically .examples field is currently preserved as is on any nested properties, even though array is not a valid format for OpenAPI examples.

{
  type: 'object',
  properties: {
    hello: {
      type: 'string',
      examples: ['world']
    }
  }
}

OpenAPI spec for example values

I will spell out my current understanding of the standard in case it will help someone in the future.

• In general, example values can be in two following formats
  • example: <value>
  • examples: {<value_name>: { value: <value>, ... }} - official documentation
• However, .examples is not supported at the top level of .schema objects, in .properties of objects and .items of arrays. This means those are only allowed to have a single example.
  • Official documentation
  • Discussion in swagger parser issues - relevant because the parser actually doesn't accept .examples in cases I just outlined
  • Previous discussion in this repo - comment by @avdwio
• Despite that, top-level of request body and response schemas can still have multiple examples, because it's possible to places .examples field outside of schema — this behavior is already implemented and covered by the test suite.
• Parameters (path, query and headers) can have either a single example or multiple examples (in the object format)

Change description

Code

• Introduced schemaTypeToNestedSchemas strategy that allows to extract all sub-schemas for different schema types.
• Introduced resolveSchemaExamples and resolveSchemaExamplesRecursive functions that only take a single example (or x-examples unchanged).
• Introduced schemaToMediaRecursive function that works the same as schemaToMedia, but also recursively resolves examples inside the schema.
• Switched resolveBodyParams and resolveResponse to recursive implementation.

Tests

Overall, I found current test coverage for example values very lacking and introduced much more extensive set of tests. Because these tests are very repetitive I had to decide whether to generalize them or not. I opted for explicit repetitive testing of each combination: single/multiple example values, parameters/body/response, shallow/deeply nested schemas, strings/numbers/objects/arrays. I added some grouping to the tests and believe explicitly testing each use case is the most maintainable approach within the current testing setup, but imho using fast-check would definitely help with repetitiveness and test quality.

The combined test file diff on this PR is a bit of a spaghetti monster, so I broke it down into two commits that are much easier to review separately.

Commit 1 - removed some tests:

• Two tests here were against the specification (asserted incorrect output)
• Four other tests that I removed for clarity of the diff output and reintroduced in the next commit

Commit 2 - added 30 explicit tests for each significant combination of configuration

Documentation

• Updated example in the README to match the implementation

Checklist

• [x] run npm run test and npm run benchmark
• [x] tests and/or benchmarks are included
• [x] documentation is changed or added
• [x] commit message and code follows the Developer's Certification of Origin and the Code of conduct

[shfrmn]

Apologies for changes after I already requested a review, but I realized there was a better implementation.

My initial solution, that you can find in the earlier commits, made changes to schemaToMedia function and introduced a boolean parameter that was used in recursion. The downsides of that approach were:

• The purpose of schemaToMedia is to augment schema into a media type object, but I was misusing it for transforming schema examples. In the process examples were first reassigned from schema to media and then back.
• Making changes to a function that's already in use is not ideal
• The second boolean parameter was awkward

New solution, even though more LoC, has several advantages:

• Doesn't mess with schemaToMedia
• Explicit intent (transforms examples within schema objects)
• Extensible, because it allows to easily add support for more nested schema types in the future (e.g. anyOf and allOf). I'm leaving it out of the scope of this PR, but might submit another one later.
• Decouples extraction of nested schemas from example resolution

[shfrmn]

@mcollina When would be a good time to merge this?

[mcollina]

Now ;)

[shfrmn]

@mcollina Sorry for bothering you, but 8.14 didn't get published after merging. Not sure if it's a CI issue or needs to be done manually.

[climba03003]

@shfrmn Published. https://www.npmjs.com/package/@fastify/swagger/v/8.14.0