Add example property / components object

[MikeRalphson]

Looking at various specification extension documentation pages, an example is a common theme. It may need to be an object with a description and value a la OAS.

[tedepstein]

I can see that examples would be useful, especially for generated documentation, and that for this purpose it's better to keep them separate from description.

Wondering if it would make more sense to put examples in the oas2, 'oas3` or other usage context objects?

Also, I'm thinking it might be a good idea to make generated documentation one of the explicitly stated use cases.

[MikeRalphson]

Hmm, as the schema doesn't vary by context, should the example(s) ?

👍 for listing documentation as a concrete use-case.

[tedepstein]

Hmm, as the schema doesn't vary by context, should the example(s) ?

As you mentioned in #18 , we might have a reason to allow context-specific schemas.

Aside from that, I think examples should be open-ended, not restricted to being just an example of the extension property value. It's often helpful to show the usage of the extension property in context. We might want to show how the extension property can be used in OAS2, OAS3, RAML, etc.