Fix examples object example and api-with-examples

[MikeRalphson]

Fixes a few issues:

• misleading comments
• examples is no longer an array anywhere
• use of $refs in examples (as opposed to example) - have preferred externalValue when refererencing whole files (which may not be json/yaml) and $ref in example which can have a fragment id. Think this is the intent.

Refs #1116

[webron]

@darrelmiller will fix more things!