feat(swagger): add OpenAPI 3.2 hierarchical tags support

[apt-bh]

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?

This PR implements the feature I requested in #3607. I wanted to give it a try myself.

Currently, TagObject only supports name, description, and externalDocs. OpenAPI 3.2 introduced hierarchical tags via parent and kind fields (doc here ), but there's no way to use them with @nestjs/swagger.

What is the new behavior?

• TagObject interface now includes optional parent and kind fields
• DocumentBuilder.addTag() accepts an optional 4th parameter for hierarchy options
• @ApiTags decorator accepts object form { name, parent?, kind? } alongside strings
• New ApiTagOptions type is exported for TypeScript users

// Define tag hierarchy at document level
const config = new DocumentBuilder()
  .addTag('Animals', 'All animal operations')
  .addTag('Cats', 'Cat operations', undefined, { parent: 'Animals' })
  .addTag('Dogs', 'Dog operations', undefined, { parent: 'Animals', kind: 'navigation' })
  .build();

// Use @ApiTags with object form for hierarchy
@ApiTags({ name: 'Cats', parent: 'Animals' })
@Controller('cats')
export class CatsController {}

// Or mix strings and objects
@ApiTags('Dogs', { name: 'Puppies', parent: 'Dogs' })
@Controller('puppies')
export class PuppiesController {}

// Existing string syntax remains fully supported
@ApiTags('Cats')
@Controller('cats')
export class CatsController {}

Note: The hierarchy info (parent, kind) is only meaningful at the document level. When using @ApiTags with objects, the name is extracted for operation-level tags (which are always string[] per OpenAPI spec), while the full hierarchy should be defined via DocumentBuilder.addTag().

Does this PR introduce a breaking change?

• Yes
• No

Other information

OpenAPI version compatibility: The parent and kind fields are part of the OpenAPI 3.2 specification. Tools that only support OpenAPI 3.0/3.1 will simply ignore these fields, so this feature is fully backward compatible.

Closes #3607