feat: improved support for response examples

[erunion]

🧰 What's being changed?

This expands upon our support for response examples by supporting the following new methods of example pulling:

• Examples in response model $ref schemas are now discovered and hoisted up into a visible example that can be rendered in the response example component.
• For responses that don't have any examples present, but have schemas, we now generate an example schema that's relevant to the types that the schema has (strings get marked a string depending on the attached format, numbers get a fake numbers, booleans a boolean, etc.). Check out feat: ability to generate sample schemas for a request and response oas#295 for some more indepth details on how this all works.
  • This work also paves the way for us to begin to surface requestBody examples as well, but that isn't included in this batch of work.

Should note that we only support this automatic example creation on non-XML media types as the objects we're composing are JSON.

🧪 Testing

To see this new example support in action, load up the "Finds Pets by status" petstore example on https://preview.readme.io/

In the definition for that operation, it has no example or examples at the media type level for the response, but the Pet schema it references has an example set on name to doggie. Previously since this example wasn't at the media type level we wouldn't be able to surface it, as shown here:

However with these improvements we're now able to surface doggie as well as flesh out the rest of the documented response with some example values:

[darrenyong]

so /pets POST and PUT methods don't show the examples since it isn't set in the response section, right?

[erunion]

@darrenyong Yeah no examples on those operations because there's no schema defined in the responses, just a description.

[darrenyong]

Looks good! This is awesome, a lot of customers are going to love this :pandaparty: