Api callbacks decorator

[MiguelSavignano]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Build related changes
• CI related changes
• Other... Please describe:

What is the current behavior?

Not possible to add callbacks property using a decorator.

What is the new behavior?

With the new @ApiCallbacks decorator is possible add callbacks in a controller method.

Does this PR introduce a breaking change?

• Yes
• No

Other information

Documentation PR nestjs/docs.nestjs.com#2621

• Create a new decorator @ApiCallbacks
• document and provide examples in PR
• define @ApiCallbacks config interface

OpenApi has a special property to define and document the callbacks https://swagger.io/docs/specification/callbacks/

This decorator allows to add in the generated OpenApi Specification of this callbacks property.

Usage

  @ApiCallbacks({
    name: 'mySecondEvent',
    callbackUrl: '{$request.body#/callbackUrl}',
    method: 'post',
    requestBody: {
      type: Cat
    },
    expectedResponse: {
      status: 200
    }
  })

Produces an OpenApi object:

{
  "callbacks": {
    "myEvent": {
      "{$request.body#/callbackUrl}": {
        "post": {
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cat"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Your server returns this code if it accepts the callback"
            }
          }
        }
      }
    }
  }
}

[destyk]

@kamilmysliwiec