fix link. + 'not yet been documented'

Currently this links to a doc which says it's out-of-date and links to the current 2.0 spec doc, so fix that link (although no mention of YAML there yet!). Also link 'Creating Swagger JSON from YAML files' which has some examples