Schema example generation should be straightened.

Background

I have been working on a couple of issues and improvements related to examples of schemas.
The biggest problem is that there are many components that are displaying examples in different ways.
Some of them are using the util getSampleSchema(). This is a function that generates sample for a provided schema and content-type. Others just use stringify() on the examples provided for requestBody or responses.

Issues

Inconsistency in components

In my opinion all components that display samples of a schema should be using the utility getSampleSchema in order to respect the content-type.

• Issue for responses #6442
• Issue for requestBody #6475
• Issue for requestBody Try-out #6476
• Issue for parameter initialValue #6791
• Issue for ExamplesSelectValueRetainer https://github.com/swagger-api/swagger-ui/issues/6918#issuecomment-775596243
  ...

Inconsistency in generation

While creating PR #6456 I noticed that the generation itself is inconsistent. The logic for integrating the example key of a schema into the generated sample is not the same for xml and json related content-type.

Swagger/OpenAPI definition:

openapi: 3.0.1
info:
 title: Example Swagger
 version: '1.0'
servers:
 - url: /api/v1
paths:
 /xmlTest:
   get:
     summary: sample issues
     operationId: registerSubscription
     parameters: []
     responses:
       '200':
         description: Simple example
         content:
           application/xml:
             schema:
               $ref: "#/components/schemas/Test"
           application/json:
             schema:
               $ref: "#/components/schemas/Test"
components:
 schemas:
   Test:
     type: object
     xml:
       name: root
     properties:
       x:
         type: string
       other:
         type: string
         format: email
     example: 
       x: what the f

The xml generator function sampleXmlFromSchema does:

• Uses parent's example of children as fallback for child schema example (Only one nesting deep)
• Uses example value merged with sample generated from schema without example
  

The json generator function sampleFromSchema instead:

• only uses only the example value or generated schema example exclusively
  

xml generator function clearly does a better job from my side.
In addition I would implement example fall back to closest parent schema's example that contains example value for current schema.

Inconsistency in handling examples

I think it would be a nice enhancement if there would be a utility that allows to parse the example value to json.

• xml -> json
• csv -> json

With this the getSampleSchema could also integrate literal examples within the generation process.

schema	-> use content-type to gen sample json
		->merge	->use content-type to stringify merged sample
raw example	->parse to json

For #6442 when using getSampleSchema there is the need to override the root schema example with content-type or media-type example. In case a property's schema itself specifies an example, this will not lead to an override, because in case of an example defined in nested schema too it will use the nested for the sample. This is why I would like to introduce an optional parameter to getSampleSchema(..., overrideExample = undefined) this could be used to override all examples at any given nesting level. Other advantage would be not missing some example values that could be used to complete the sample.

Would like to hear some thoughts on this before I start developing.

Open Questions

• Does the getSampleSchema fit the #6442 use case with merge and override logic? Or would it be a better approach to just parse the example value to JSON and then stringify it respectingly to the content-type or media type without merging schema sample?
• How to display just a response or requestBody example, without taking schema into consideration, using override with merge approach?

Start by tracing getSampleSchema and compare the existing sampleXmlFromSchema and sampleFromSchema generation paths. Review the related issues #6442, #6475, #6476, and #6791, then resolve the open questions about parsing, merging, and overriding examples with maintainers. Done means an agreed behavior and implementation scope for consistent schema examples across components.