Support deprecated tag when generating output

[Dashron]

The goal is to be able to indicate that a field, endpoint, parameter etc. is "the wrong way", and has been replaced with a better way.

eg from the Vimeo API: The upload_link parameter is now HTTPS, which means there is no need for the upload_link_secure parameter because the urls are now identical. We should have the option to exclude upload_link_secure from most docs, and include it in others with a clear warning that upload_link_secure should no longer be used, and will be removed in future versions.

Ideally we would be able to explain what the better way is alongside the deprecation annotation.

[erunion]

We originally had an @api-deprecated annotation, but ended up moving that to be a special "decorator" for URI's and parameters only (eg. @api-uri:public:deprecated).

I think the best thing to do is just revive it as a representation-only annotation.

/**
 * @api-label Upload URL (secure).
 * @api-field upload_link_secure
 * @api-type string
 * @api-version <=3.3
 * @api-deprecated Deprecated in favor of `upload_link` resolving to a HTTPS URL.
 */

And also since API Blueprint doesn't support deprecation, we can just shove the @api-deprecated description onto the data label. So in generated Markdown for versions <=3.3, it'll end up as:

- `upload_link_secure` (string) - Upload URL (secure). Deprecated in favor of `upload_link` resolving to a HTTPS URL.