feat(api-header): add example property to ApiHeader decorator

[leemhoon00]

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?

When using the @ApiHeader decorator with the example field (not examples) on methods or controllers:

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @ApiHeader({
    name: 'test',
    example: 'example-data',
  })
  @Get()
  getHello() {
    console.log('Hello World');
  }
}

then

it is not applied

Issue Number: N/A

What is the new behavior?

example field are applied

Does this PR introduce a breaking change?

• Yes
• No

Other information

According to OpenAPI 3.0 Parameter Object, example should be placed inside schema.

[kamilmysliwiec]

Could you please update e2e tests too?

[leemhoon00]

Could you please update e2e tests too?

Thank you for the feedback.

From what I can see, the e2e tests don’t explicitly check for headers. Are we simply expected to:

1. Add the example field in @ApiHeader in CatController,

@ApiHeader({
  name: 'header',
  required: false,
  description: 'Test',
  schema: { default: 'test' },
  example: 'test'
})

2. Regenerate the api-spec.json, and commit it?

Or do we also need to include a validation check in validate-schema.e2e-spec.ts, like this?

expect(
    api.paths['/api/cats']['get']['parameters'][0]['schema']['example']
  ).toBe('test');

[kamilmysliwiec]

no need to check it here