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?

SecuritySchemes cannot include additional necessary information. Specifically, for security implementations requiring more than one header, the current Security Scheme Object cannot represent such configurations. This limitation makes it difficult to express security setups for platforms like AWS API Gateway, which often require additional metadata.

Issue Number: #3179

What is the new behavior?

Added support for custom extension properties in the SecuritySchemeObject

example code when used addApiKey()

.addApiKey({
    type: 'apiKey',
    name: 'Authorization',
    in: 'header',
    'x-amazon-apigateway-authtype': 'oauth2',
    'x-amazon-apigateway-authorizer': {
        type: 'token',
        authorizerUri:
            'arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations',
        authorizerCredentials: 'arn:aws:iam::account-id:role',
        identityValidationExpression: '^x-[a-z]+',
        authorizerResultTtlInSeconds: 60,
    },
})

When creating a Swagger document, you can now include custom extensions in the Security Scheme Object using methods like .addApiKey(), .addBearerAuth(), .addOAuth2(), or .addBasicAuth(). This feature enables you to define additional metadata required for platforms like AWS API Gateway or other custom security configurations.

Does this PR introduce a breaking change?

• Yes
• No

Other information

reference: https://swagger.io/docs/specification/v3_0/openapi-extensions/