feat: adds @deprecated convenience decorator

[mschnee]

Partially implements: #4300
See: #4406

This has been split from #4406 as a more manageable, smaller PR.

Added

This PR adds @deprecated to Controller classes and methods, and marks all paths as deprecated: true in accordance with the OpenAPI Operation Object specification.

As the spec defines deprecated as an optional property, this feature will only add deprecated: true and never deprecated: false.

Not (yet) supported

This PR does not add support for marking parameters as deprecated

Examples

@deprecated()
class MyController {
   @get('/greet')
   public async function greet() {
    return 'Hello, World!'
  }

  @get('/greet-v2')
  @deprecated(false)
  public async function greetV2() {
    return 'Hello, World!'
  }
}

class MyOtherController {
  @get('/echo')
  @deprecated()
  public async function echo() {
    return 'Echo!'
  }
}

Checklist

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• (n/a) Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

[mschnee]

Note: The Node 8 build failed due to a 404 from http://calculator-webservice.mybluemix.net/calculator?wsdl, which at the moment (2 hours later) is not returning a 404. Will trigger a new build.

[bajtos]

Thank you @mschnee for the contribution. The changes look good to me at high level, I'd like @jannyHou to review OpenAPI-specific parts and @raymondfeng to review how the decorator is defined using metadata APIs.

[raymondfeng]

My only concern is that @deprecated may confuse our developers as it's not obvious for OpenAPI spec only. See similar discussion at #4416 (comment).

@strongloop/loopback-maintainers What do you think?

[jannyHou]

@mschnee Thank you so much for improving the OpenAPI series decorators! 🙇
I agree with @raymondfeng 's suggestion that uses a namespace to organize the operation decorators. Otherwise your code LGTM 👍

[dougal83]

As the spec defines deprecated as an optional property, this feature will only add deprecated: true and never deprecated: false.

Thinking about it, it wouldn't hurt to explicitly default to setting depreciated: false as the last property of a PathsObject. Considering the default is false it would be informational. Probably outside the scope of this PR.

[mschnee]

Squash will happen after all the tests are clean :)