Add deprecated functionality

[deanmaunder]

Summary

There's currently no way to mark a whole API operation as deprecated via handler annotations. cbSwagger supports deprecated: true
on parameters and schema properties (passed through verbatim in the JSON convention files), but the OpenAPI operation-level
deprecated flag can't be set from a handler function attribute or docblock tag.

Current behaviour

RoutesParser builds each operation from OpenAPIUtil.newMethod(), whose template has no deprecated key. The generic annotation
parser only assigns keys already present in that template (defaultKeys), so a deprecated="true" function attribute is silently
dropped. An x-deprecated annotation is emitted only as a non-standard vendor extension, which renderers like Redoc ignore — so
there's no supported path to a standard operation-level deprecated: true.

Proposed behaviour

Allow handler actions to declare deprecation and have it emit standard OpenAPI:

// function attribute
function list( event, rc, prc ) deprecated="true" description="List Foo" {}

// or docblock
/**
 * @deprecated true
 */
function list( event, rc, prc ) {}

→ generated operation object:

{ "deprecated": true, "summary": "List Foo" }

The annotation value must be coerced to a real JSON boolean — function attributes arrive as strings ("true"), which would otherwise
serialise incorrectly. Operations without the annotation should default to deprecated: false.