Add support for Swagger/OpenAPI Extensions

I’m submitting a…

[ ] Regression 
[ ] Bug report
[X] Feature request
[ ] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

There are no decorators for the Open Api Extensions

Swagger Doc

Java Decorator Example

Expected behavior

This is an example of this decorator in Java Swagger module

    @ApiOperation(value = "/ranking/calcio",
            httpMethod = "GET",
            extensions = @Extension(name = "x-amazon-apigateway-integration", properties = {
                    @ExtensionProperty(name = "uri", value = "http://HTTP_ENDPOINT/sportsdata/api/rest/ranking/calcio"),
                    @ExtensionProperty(name = "connectionType", value = "VPC_LINK"),
                    @ExtensionProperty(name = "connectionId", value = "VPC_LINK_ID"),
                    @ExtensionProperty(name = "httpMethod", value = "GET"),
                    @ExtensionProperty(name = "type", value = "http_proxy")
            }))

That produces this output in the swagger.json file:

"/ranking/calcio" : {
      "get" : {
        "tags" : [ "Ranking API" ],
        "summary" : "/ranking/calcio",
        "description" : "",
        "operationId" : "footballRankingRest",
        "parameters" : [ /* ... */],
        "responses" : {
          "200" : {
            "description" : "The football ranking",
            "schema" : {
              "$ref" : "#/definitions/ResponseBean"
            }
          }
        },
        "x-amazon-apigateway-integration" : {
          "connectionId" : "VPC_LINK_ID",
          "httpMethod" : "GET",
          "type" : "http_proxy",
          "uri" : "http://HTTP_ENDPOINT/sportsdata/api/rest/ranking/calcio",
          "connectionType" : "VPC_LINK"
        }
      }
    }
]

What is the motivation / use case for changing the behavior?

At this time this is blocking because we need this extension in order to use the swagger.json to generate Amazon API Gateway definition files

I did not find any doc on how to create/extend existing decorators, if you point me to the right direction i can try to implement it

Thank you for your amazing work

[tomchinery]

@CesarBMartinez I’ll take a look into it and see if I can raise a PR.

[mikrivorot]

Some solution can be done locally in the application without changes in nest/swagger

My goal was to add custom swagger parameters to request body (decorator ApiModelProperty)

1. Use {showExtensions: true} in main.ts (necessary for UI, because even if you have custom parameters on back and in json in UI, it will be not renderred without this property):

SwaggerModule.setup('api', app, document, {swaggerOptions: {showExtensions: true}});

1. Create your own decorator and extend metadata in your project file:

import  {ApiModelProperty} from '@nestjs/swagger'

type SwaggerDecoratorParams  = Parameters<typeof ApiModelProperty>;
type SwaggerDecoratorMetadata = SwaggerDecoratorParams [0];
type MyAwesomeMetadata = SwaggerDecoratorMetadata & CustomSwaggerParameters;

export const MyAwesomeDecorator = (params: MyAwesomeMetadata) => {
  return ApiModelProperty(params);
};

class CustomSwaggerParameters {
  'x-ui-test'?: boolean;
}

1. Use it

import {MyAwesomeDecorator as ApiModelProperty}  from "somepath/in/project";

export class TestParameters {
  @ApiModelProperty({minimum: 1, example: 1, 'x-ui-test': true})
  public testParameter: number;
}