feat: adds @oas.response decorator

[mschnee]

Partially implements: #4300
See: #4406

Adds

This PR adds the @oas.response(code: number, ...modelOrSpec: ModelOrSpec[]) decorator.

Note

The decorator only affects the OpenAPI specification object that is created, and anything that uses it to verify and validate responses. This decorator has no impact on the actual response code. It also doesn't add any typings or lint configuration that could force response compliance at compile/lint time (if that's even possible).

Example

@model()
class SuccessModel extends Model {
  constructor(err: Partial<SuccessModel>) {
    super(err);
  }
  @property({default: 'Hi there!'})
  message: string;
}

class FooNotFound extends Model {
  @property()
  message: string;
}

class BarNotFound extends Model {
  @property()
  message: string;
}

class BazNotFound extends Model {
  @property()
  message: string;
}

class MyController {
  @oas.get('/greet/{foo}/{bar}',
  @oas.response(200, SuccessModel)
  @oas.response(404, FooNotFound, BarNotFound)
  @oas.response(404, BazNotFound)
  greet() {
    return new SuccessModel({message: 'Hello, world!'});
  }
}

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
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

[mschnee]

Note: I'd love to figure out some way to use these decorators as response code hints in the future, but I'm not entirely sure how to go about doing that in a way that fits the current patterns.

e.g.

@oas.response(404, SomeErrorModel)

If the invoked method returns or throws instanceof SomeErrorModel (or ideally, a more direct test), and that model isn't associated with any other status codes for that route, and if the status has not already been set explicitly, then assume the developer intends to return 404.

[raymondfeng]

@mschnee Can you rebase your PR against latest master branch with git fetch --all && git rebase upstream/master?

[mschnee]

Rebased from upstream and squashed!

[bajtos]

I love the user experience of the proposed API 👍

I'll leave the detailed review and approval to @raymondfeng.

[raymondfeng]

I don't see http-status as a dev dependency.

[raymondfeng]

This should require http-status to be a dev dependency. The build is passing because the module is transitively added as follows:

rest
└─┬ [email protected]
  └── [email protected] 

[raymondfeng]

This makes http-status a regular dependency (instead of dev). Please add it to package.json.

[raymondfeng]

It should be import httpStatus from 'http-status' now.

[mschnee]

I'll make these changes today