OpenAPI (Swagger) module for Nest framework (node.js) :earth_americas:

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• [x] 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?

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

What is the current behavior?

Issue Number: N/A

What is the new behavior?

Changes/features

• the overall codebase refactor (improve typings, extract common functionalities)
• add tests (+ validate schema against OpenAPI validator)
• migrate to OpenAPI 3.0
• add security-related decorators (e.g. @ApiSecurity(), @ApiBasicAuth())
• allow specifying schema manually for more sophisticated scenarios (e.g. nested arrays)
• breaking changes:

1. All @ApiImplicit{...} decorators have been changed to @Api{...}, for example, @ApiImplicitBody() -> @ApiBody() - reason: the name was confusing because this operation actually wasn't "implicit".
2. Both @ApiResponseProperty() and @ApiModelProperty -> @ApiProperty().

Fixes

• https://github.com/nestjs/swagger/issues/350
• https://github.com/nestjs/swagger/issues/342
• https://github.com/nestjs/swagger/issues/341
• https://github.com/nestjs/swagger/issues/324
• https://github.com/nestjs/swagger/issues/315
• https://github.com/nestjs/swagger/issues/312
• https://github.com/nestjs/swagger/issues/311
• https://github.com/nestjs/swagger/issues/275
• https://github.com/nestjs/swagger/issues/257
• https://github.com/nestjs/swagger/issues/250
• https://github.com/nestjs/swagger/issues/245
• https://github.com/nestjs/swagger/issues/237
• https://github.com/nestjs/swagger/issues/192
• https://github.com/nestjs/swagger/issues/191
• https://github.com/nestjs/swagger/issues/185
• https://github.com/nestjs/swagger/issues/181
• https://github.com/nestjs/swagger/issues/176
• https://github.com/nestjs/swagger/issues/172
• https://github.com/nestjs/swagger/issues/147
• https://github.com/nestjs/swagger/issues/139
• https://github.com/nestjs/swagger/issues/140
• https://github.com/nestjs/swagger/issues/130
• https://github.com/nestjs/swagger/issues/83
• https://github.com/nestjs/swagger/issues/63
• https://github.com/nestjs/swagger/issues/116

Future

As I've mentioned in this issue https://github.com/nestjs/swagger/issues/191, I planned to rewrite the entire package to use AST and generate JSON schema as an additional compilation step. However, this change would make the usage of the package slightly more complicated. In addition, most of the code written so far would have to be removed. Hence, I came up with another solution.

The entire package has been somewhat refactored & most of the common issues should be addressed within this PR. Now, the next step would be to create a plugin.

As you can read in this https://trilon.io/blog/announcing-nestjs-monorepos-and-new-commands blog post, new CLI features introduced plugins system. Thus, we can easily use the existing package and add some new features on top of it based on the AST and pre-compilation hook.

The plugin would allow us to:

• generate the default responses (based on the return type - extracted either Promise or Observable)
• automatically add @ApiProperty() if not present
• automatically set the property to either required: true or required: false depending on the question mark ? (optional value)
• automatically transform arrays, for example

before:
----
@ApiProperty()
tags: string[]

after (this step is automated - "behind the curtain"):
----
@ApiProperty({ type: [String] })
tags: string[]

• conditionally (if enabled) merge class-validator validation rules with OpenAPI properties
• support generics (and maybe interfaces?, i'm not sure about the potential use-case yet)

Does this PR introduce a breaking change?

[x] Yes
[ ] No

Other information

I'm submitting a...

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

Current behavior

All swagger schemas are empty and contain no information at all.

Expected behavior

Documentation detailing the property types on schemas should be inferred from the typescript definitions as described here and here. Like so:

Minimal reproduction of the problem with instructions

Reproduction: https://github.com/robertmain/meal-plan/tree/update-swagger

Instructions:

1. Download the app from the link above (the branch is important!) 1 Install the dependencies and navigate to localhost:3000/api (yeah, I know it's a crappy URL scheme...I'm working on it)

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

Empty API documentation isn't very useful...? :thinking:

Environment

Nest version: 6.6.4

For Tooling issues:

• Node version: 10.16.3
• Platform: Debian Linux 9

Others:

Contents of nest-cli.json

{
  "language": "ts",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger/plugin"]
  }
}

The @nestjs/swagger is one of the most widely used @nestjs packages under the @nestjs organization. So far it works pretty great - we have a declarative way to easily generate OpenAPI specification using decorators placed near to our DTOs/routes, we cover 3/4 potential use-cases providing a quite simple API to interact with.

However, the current model of this library doesn't fit the requirements which we should set ourselves in order to ensure that we provide the best quality for developers. Let me list a number of them.

• massive redundancy (lots of decorators that shouldn't be required)
• lack of consistency (if we want to change our property to an optional one, we very likely have to add @IsOptional() - for the validation purposes, change the decorator to @ApiModelPropertyOptional() and add a question ? mark by the end of the property name)
• no generics support
• no interfaces support
• no auto-response schemas generation
• lack of flexibility (hard to add custom rules/decorators/interpreters)
• no circular-dependencies support

The main reason for all of these outlined issues is weak TypeScript reflection capability. Hence, the library itself will be very likely rewritten and will use TypeScript AST to support all these amazing features out-of-the-box.

I have created this issue in order to share plans with you as well as encourage you to share your personal experiences with this library - if there is something else that was very troublesome/unsupported so far, please, let me know here - we can work on the design specification together.

I'm submitting a...

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

Current behavior

nest start fails with new swagger plugin

Expected behavior

app started

Minimal reproduction of the problem with instructions

https://github.com/gulaandrij/nest-monorepo-swagger steps:

yarn install
nest start

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

Environment

[System Information]
OS Version     : Linux 5.3
NodeJS Version : v13.1.0
YARN Version    : 1.19.2

[Nest Information]
platform-express version : 6.7.2
swagger version          : 4.0.2
common version           : 6.7.2
core version             : 6.7.2

I'm submitting a...

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

Current behavior

Hello I am having issue only on JENKINS with the following package.json "dependencies": { "@nestjs/common": "7.4.4", "@nestjs/core": "7.4.4", "@nestjs/microservices": "7.4.4", "@nestjs/platform-express": "7.4.4", "@nestjs/swagger": "^4.6.1", "@nestjs/typeorm": "7.1.4", "@nestjs/websockets": "7.4.4",

The issue doesnt occur on Windows or MAC. Not sure what is failing on Jenkins which runs on Linux version. PLEASE HELP.....

core_1 | 2020-10-22T19:42:23.472811670Z INFO: All classes found using provided glob pattern "/jail-service/core/session/session.entity{.ts,.js}" : "/jail-service/core/session/session.entity.js"

core_1 | 2020-10-22T19:42:23.540807215Z (node:93) UnhandledPromiseRejectionWarning: Error: A circular dependency has been detected (property key: "screening"). Please, make sure that each side of a bidirectional relationships are using lazy resolvers ("type: () => ClassType").

core_1 | 2020-10-22T19:42:23.540828602Z at SchemaObjectFactory.createNotBuiltInTypeReference (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:190:19)

core_1 | 2020-10-22T19:42:23.540832079Z at SchemaObjectFactory.mergePropertyWithMetadata (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:121:25)

core_1 | 2020-10-22T19:42:23.540835103Z at /jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:67:35

core_1 | 2020-10-22T19:42:23.540837948Z at Array.map ()

core_1 | 2020-10-22T19:42:23.540840485Z at SchemaObjectFactory.exploreModelSchema (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:66:52)

core_1 | 2020-10-22T19:42:23.540843184Z at SchemaObjectFactory.createNotBuiltInTypeReference (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:195:37)

core_1 | 2020-10-22T19:42:23.540845978Z at SchemaObjectFactory.mergePropertyWithMetadata (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:121:25)

core_1 | 2020-10-22T19:42:23.540848594Z at /jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:67:35

core_1 | 2020-10-22T19:42:23.540851132Z at Array.map ()

core_1 | 2020-10-22T19:42:23.540854255Z at SchemaObjectFactory.exploreModelSchema (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:66:52)

core_1 | 2020-10-22T19:42:23.540859186Z at SchemaObjectFactory.createNotBuiltInTypeReference (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:195:37)

core_1 | 2020-10-22T19:42:23.540863225Z at SchemaObjectFactory.mergePropertyWithMetadata (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:121:25)

core_1 | 2020-10-22T19:42:23.540867307Z at /jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:67:35

core_1 | 2020-10-22T19:42:23.540871059Z at Array.map ()

core_1 | 2020-10-22T19:42:23.540874307Z at SchemaObjectFactory.exploreModelSchema (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:66:52)

core_1 | 2020-10-22T19:42:23.540877053Z at SchemaObjectFactory.createNotBuiltInTypeReference (/jail-service/node_modules/@nestjs/swagger/dist/services/schema-object-factory.js:195:37)

core_1 | 2020-10-22T19:42:23.540880358Z (Use node --trace-warnings ... to show where the warning was created)

core_1 | 2020-10-22T19:42:23.540890259Z (node:93) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag --unhandled-rejections=strict (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)

core_1 | 2020-10-22T19:42:23.540894180Z (node:93) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Expected behavior

Minimal reproduction of the problem with instructions

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

Environment

Nest version: X.Y.Z

 
For Tooling issues:
- Node version: XX  
- Platform:  

Others:

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• [x] 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
[x] 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?

Current behavior is when an Enum is defined and used on a Model, the Enum values are put on the properties of the Model itself.

This causes Frontend Generation Tools (such as NSwag) to generate multiple enums even though they are meant for the same thing.

Issue Number: #372

What is the new behavior?

~~New behavior will expect: enum property on various decorator (ApiParam, ApiQuery, ApiProperty) to accept a lazy-function syntax.~~

~~This allows SwaggerExplorer to grab the Enum name at run-time which makes it possible to extract the Enum out to schemas to be reused on Parameters~~

~~Please note this is an addition, not replacement. enum property still accepts what it currently accepts. This PR makes it so it will solve the issue stated in Current Behavior with lazy function syntax.~~

Various decorators that accept enum now also accept enumName. If you want your enum to be store as a schema (reusable) then you need to provide enumName as well. This implementation might seem a little bit explicit compared to the lazy load function but its intention is also clearer.

// before
@ApiProperty({enum: Role})

// later
@ApiProperty({enum: Role, enumName: 'Role'})

Again, although the PR is working, maintain the current passing tests, passing two new tests, my implementation might contain flaws and might go against NestJS's design mental. That said, I'm open to ALL suggestions and feedbacks.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

I'm submitting a...

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

Current behavior

When setting setGlobalPrefix('v2') and using the Swagger module as described in the doc with SwaggerModule.setup('api', app, document), the API is actually available under /api and /v2/api throws a 404 Cannot GET /v2/api.

It works when setting SwaggerModule.setup('v2/api', app, document), but this introduces duplication.

Expected behavior

I expected the global prefix to be applied to the Swagger module's path, too.

Minimal reproduction of the problem with instructions

Repro repo. Created with the CLI, only added swagger module as described in the doc and setGlobalPrefix().

Environment

Nest version: 5.0.1

Make the behavior change for operation names that was introduced in https://github.com/nestjs/swagger/pull/487 configurable, and allow users whose client libraries have broken because of this (see https://github.com/nestjs/swagger/issues/482) to configure this behavior.

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• [x] Tests for the changes have been added (for bug fixes / features)
• [x] Docs have been added / updated (for bug fixes / features) yes, see https://github.com/nestjs/docs.nestjs.com/pull/1247

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] 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?

Since #487 was merged, operation IDs generated by NestJS changed from e.g.

addUser

to

UserController_addUser

... this is causing users of generated client libraries (e.g. Angular) to have to update all their service calls to unnecessarily long names, e.g. from designService.updateImages to designService.frontendDesignsControllerUpdateImages (see https://github.com/nestjs/swagger/issues/482#issuecomment-577777620).

Issue Number: N/A

What is the new behavior?

This PR allows users to configure this behavior. By default, nothing changes, unless the user configures @nestjs/swagger with a custom operationIdFactory:

const app = await NestFactory.create(AppModule);
const operationIdFactory = (
  controllerKey: string,
  methodKey: string
) => `${methodKey}`;

const options = new DocumentBuilder()
  .setTitle('Cats example')
  .setDescription('The cats API description')
  .setVersion('1.0')
  .addTag('cats')
  .build();
const document = SwaggerModule.createDocument(app, options, {
  operationIdFactory
});
SwaggerModule.setup('api', app, document);

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

I'm submitting a...

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

Current behavior

Controller method:

Swagger result:

=> configurationName and module is reversed :/ This has the consequence that e.g. NSwag generated methods also have the wrong parameter order.

Expected behavior

The Swagger doc respects the source-code order.

Bug cause

The problem is that the route parameters decorator metadata (ROUTE_ARGS_METADATA) contains a object, not an array (as DECORATORS.API_PARAMETERS does). => exploreApiReflectedParametersMetadata doesn't return the correct order.

See the following debugger screenshot.

Sorting parameters by the object keys (i.e. 5:0, 5:1 in the shown example) explicitly, using ...

const sortedParameters = lodash_1.map(lodash_1.sortBy(lodash_1.map(parameters, (item, name) => ({item, name})), 'name'), x => x.item);

... fixes the issue (see also debugger screenshot).

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

no decorator to automate swagger schema generation for HttpException

Expected behavior

Minimal reproduction of the problem with instructions

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

Environment

Nest version: 7.x
Nest swagger: 4.x

Example of implementation

import { HttpException, Type } from '@nestjs/common';
import { ApiResponse, ApiResponseOptions, getSchemaPath } from '@nestjs/swagger';
import { getTypeIsArrayTuple } from '@nestjs/swagger/dist/decorators/helpers';
import { ResponseObject, SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';

export type Func = () => void;

export interface ApiExceptionOptions extends Omit<ResponseObject, 'description'> {
    description?: string;
    type?: Func | [Func];
    isArray?: boolean;
    schema?: SchemaObject;
}

export const ApiException = <T extends HttpException>(exception: () => Type<T>, options: ApiExceptionOptions = {}): MethodDecorator & ClassDecorator => {
    const instance = new (exception())();

    const apiResponseOptions: ApiResponseOptions = {
        status: instance.getStatus(),
        description: options?.description || instance.message,
        schema: {
            type: 'object',
            properties: {
                statusCode: {
                    type: 'number',
                    example: instance.getStatus(),
                },
                message: {
                    type: 'string',
                },
                error: {
                    type: 'string',
                    example: instance.message,
                },
            },
            required: ['statusCode', 'message'],
        },
    };

    if (options.schema) {
        apiResponseOptions.schema.properties!.message = options.schema;
    } else if (options.type) {
        const [type, isArray] = getTypeIsArrayTuple(options.type, !!options.isArray);
       // For standard data types (Object, String, etc), an error will be shown on the swagger api page, I don't know how to get around it
        apiResponseOptions.schema.properties!.message['$ref'] = getSchemaPath(type!());

        if (isArray) {
            apiResponseOptions.schema.properties!.message = {
                type: 'array',
                items: {
                    type: 'object',
                    $ref: apiResponseOptions.schema.properties!.message['$ref'],
                },
            };
        }
    }

    return ApiResponse(apiResponseOptions);
};

examples

@ApiException(() => NotFoundException)
@ApiException(() => NotFoundException, { description: 'Custom description' })
@ApiException(() => NotFoundException, { description: 'Custom description', schema: { /** custom schema for message prop */} }
@ApiException(() => NotFoundException, { description: 'Custom description', type: () => SomeClassWithSwaggerAnnotitions, isArray: true }

I'm submitting a...

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

I'm using nestjs/swagger and trying to figure out a way to upload a file and also pass additional form data along with the image.

I'm using this to upload the image, and it works fine.

  @UseInterceptors(FileInterceptor('file'))
  @ApiConsumes('multipart/form-data')
  @ApiImplicitFile({ name: 'file', required: true })
  uploadFile(@UploadedFile() file) {
    console.log('got upload');
    console.log('...file', file);
  }

However, I'd like to include some meta data about my file as form data. I tried using @Body(), but that expects a json payload, and the upload requires multipart/form-data.

  @UseInterceptors(FileInterceptor('file'))
  @ApiConsumes('multipart/form-data')
  @ApiImplicitFile({ name: 'file', required: true })
  uploadFile(@UploadedFile() file, @Body() body: MyDto) {
    console.log('got upload');
    console.log('...file', file);
    console.log('...body', body);
  }

I also tried ApiImplicitBody, but couldn't seem to get it to work. I'm just guessing because I seem to be deep in undocumented territory.

What is the correct way to:

• Access other properties of the multi-part form (beyond the file)
• Define that as part of the swagger definition with the swagger decorators

This PR contains the following updates:

| Package | Change | |---|---| | json5 | 1.0.1 -> 1.0.2 | | json5 | 2.2.1 -> 2.2.2 |

GitHub Vulnerability Alerts

CVE-2022-46175

The parse method of the JSON5 library before and including version 2.2.1 does not restrict parsing of keys named __proto__, allowing specially crafted strings to pollute the prototype of the resulting object.

This vulnerability pollutes the prototype of the object returned by JSON5.parse and not the global Object prototype, which is the commonly understood definition of Prototype Pollution. However, polluting the prototype of a single object can have significant security impact for an application if the object is later used in trusted operations.

Impact

This vulnerability could allow an attacker to set arbitrary and unexpected keys on the object returned from JSON5.parse. The actual impact will depend on how applications utilize the returned object and how they filter unwanted keys, but could include denial of service, cross-site scripting, elevation of privilege, and in extreme cases, remote code execution.

Mitigation

This vulnerability is patched in json5 v2.2.2 and later. A patch has also been backported for json5 v1 in versions v1.0.2 and later.

Details

Suppose a developer wants to allow users and admins to perform some risky operation, but they want to restrict what non-admins can do. To accomplish this, they accept a JSON blob from the user, parse it using JSON5.parse, confirm that the provided data does not set some sensitive keys, and then performs the risky operation using the validated data:

const JSON5 = require('json5');

const doSomethingDangerous = (props) => {
  if (props.isAdmin) {
    console.log('Doing dangerous thing as admin.');
  } else {
    console.log('Doing dangerous thing as user.');
  }
};

const secCheckKeysSet = (obj, searchKeys) => {
  let searchKeyFound = false;
  Object.keys(obj).forEach((key) => {
    if (searchKeys.indexOf(key) > -1) {
      searchKeyFound = true;
    }
  });
  return searchKeyFound;
};

const props = JSON5.parse('{\"foo\": \"bar\"}');
if (!secCheckKeysSet(props, ['isAdmin', 'isMod'])) {
  doSomethingDangerous(props); // \"Doing dangerous thing as user.\"
} else {
  throw new Error('Forbidden...');
}

If the user attempts to set the isAdmin key, their request will be rejected:

const props = JSON5.parse('{\"foo\": \"bar\", \"isAdmin\": true}');
if (!secCheckKeysSet(props, ['isAdmin', 'isMod'])) {
  doSomethingDangerous(props);
} else {
  throw new Error('Forbidden...'); // Error: Forbidden…
}

However, users can instead set the __proto__ key to {\"isAdmin\": true}. JSON5 will parse this key and will set the isAdmin key on the prototype of the returned object, allowing the user to bypass the security check and run their request as an admin:

const props = JSON5.parse('{\"foo\": \"bar\", \"__proto__\": {\"isAdmin\": true}}');
if (!secCheckKeysSet(props, ['isAdmin', 'isMod'])) {
  doSomethingDangerous(props); // \"Doing dangerous thing as admin.\"
} else {
  throw new Error('Forbidden...');
}

Configuration

📅 Schedule: Branch creation - "" (UTC), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

👻 Immortal: This PR will be recreated if closed unmerged. Get config help if that's undesired.

• [ ] If you want to rebase/retry this PR, check this box

This PR has been generated by Mend Renovate. View repository job log here.

Bumps json5 from 1.0.1 to 1.0.2.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Is there an existing issue for this?

• [X] I have searched the existing issues

Current behavior

If any @ApiSecurity() decorator is present on a route, then the Available authorizations registered by global .addSecurityRequirements() on the route are gone.

Minimum reproduction code

https://github.com/zetaraku/nest-demo

Steps to reproduce

1. Run npm install
2. Run npm run start:dev
3. Goto the /api route
4. Click the lock icons on both /without-decorator and /with-decorator route

Expected behavior

The local security requirements should be merged with the global security requirements so that both requirements are present.

Package version

6.1.4

NestJS version

9.0.0

Node.js version

16.17.0

In which operating systems have you tested?

• [ ] macOS
• [X] Windows
• [ ] Linux

Other

No response

Support added of ApiParam and ApiQuery for Controller, PR Reference #1332

PR Checklist

Please check if your PR fulfills the following requirements:

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

PR Type

What kind of change does this PR introduce?

• [ ] Bugfix
• [x] 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?

Put ApiParam on every route method in controller.

@Controller('tests/:testId')
class TestAppController {
  @ApiParam({ name: 'testId' })
  @ApiQuery({ name: 'testQuery'})
  @Get()
  public method1(@Param('testId') testId: string, @Query('testQuery') testQuery: string) {
  }

  @ApiParam({ name: 'testId' })
  @ApiQuery({ name: 'testQuery'})
  @Get()
  public method2(@Param('testId') testId: string, @Query('testQuery') testQuery: string) {
  }
}

Issue Number: #2200

What is the new behavior?

I would like ApiParam to support the class decorator to reduce the waste of time.

@ApiParam({ name: 'testId' }) //new
@ApiQuery({ name: 'testQuery'}) //new
@Controller('tests/:testId')
class TestAppController {
  @Get()
  public method1(@Param('testId') testId: string, @Query('testQuery') testQuery: string) {
  }

  @Get()
  public method2(@Param('testId') testId: string, @Query('testQuery') testQuery: string) {
  }
}

Does this PR introduce a breaking change?

• [ ] Yes
• [x] No

Other information

NestJs Docs updated: https://github.com/nestjs/docs.nestjs.com/pull/2570

Is there an existing issue that is already proposing this?

• [X] I have searched the existing issues

Is your feature request related to a problem? Please describe it

@ApiParam is not supported in controllers, I don't know if there's any specific reason why it doesn't. But in the use case that I have, it makes sense to be able to use it directly in the controller.

In the example below, I will have to define @ApiParam('it_projeto') in each method, even if it is a param in the controller route.

import { Body, Controller, Get, Param, Post } from '@nestjs/common';
import { ApiParam, ApiTags } from '@nestjs/swagger';
import { CriarIntencaoDto } from './criar-intencao.dto';
import { IntencaoService } from './intencao.service';

@ApiTags('intencao')
@Controller('projeto/:it_projeto/intencao')
export class IntencaoController {
  constructor(private readonly intencaoService: IntencaoService) {}

  @ApiParam({
    name: 'it_projeto',
    type: 'number',
    description: 'Código do projeto',
  })
  @Get()
  listar(@Param() { it_projeto }) {
    return this.intencaoService.listar(it_projeto);
  }

  @ApiParam({
    name: 'it_projeto',
    type: 'number',
    description: 'Código do projeto',
  })
  @Post()
  criar(@Param() { it_projeto }, @Body() payload: CriarIntencaoDto) {
    return this.intencaoService.criar(it_projeto, payload);
  }
}

Describe the solution you'd like

I believe that support for class and method would already solve this problem. I don't particularly see any downsides.

Example

import { Body, Controller, Get, Param, Post } from '@nestjs/common';
import { ApiParam, ApiTags } from '@nestjs/swagger';
import { CriarIntencaoDto } from './criar-intencao.dto';
import { IntencaoService } from './intencao.service';

@ApiTags('intencao')
@ApiParam({
  name: 'it_projeto',
  type: 'number',
  description: 'Código do projeto',
})
@Controller('projeto/:it_projeto/intencao')
export class IntencaoController {
  constructor(private readonly intencaoService: IntencaoService) {}

  @Get()
  listar(@Param() { it_projeto }) {
    return this.intencaoService.listar(it_projeto);
  }

  @Post()
  criar(@Param() { it_projeto }, @Body() payload: CriarIntencaoDto) {
    return this.intencaoService.criar(it_projeto, payload);
  }
}

Teachability, documentation, adoption, migration strategy

On the page https://docs.nestjs.com/openapi/decorators I believe the only change for the user would be to add "Method/Controller" in the @ApiParam info.

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

Decrease decorator usage for expected parameters in the controller route.

This PR contains the following updates:

| Package | Type | Update | Change | |---|---|---|---| | cimg/node | docker | minor | 18.10 -> 18.12 |

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

• [ ] If you want to rebase/retry this PR, check this box

This PR has been generated by Mend Renovate. View repository job log here.