Skip to content

docs(openapi): document OpenAPI 3.2 hierarchical tags#3409

Open
apt-bh wants to merge 1 commit into
nestjs:masterfrom
apt-bh:docs/openapi-v32-hierarchical-tags
Open

docs(openapi): document OpenAPI 3.2 hierarchical tags#3409
apt-bh wants to merge 1 commit into
nestjs:masterfrom
apt-bh:docs/openapi-v32-hierarchical-tags

Conversation

@apt-bh
Copy link
Copy Markdown

@apt-bh apt-bh commented Apr 20, 2026

PR Checklist

Please check if your PR fulfills the following requirements:

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
  • Docs
  • Other... Please describe:

What is the current behavior?

The OpenAPI "Operations" page only documents the string form of @ApiTags and the basic
DocumentBuilder.addTag(name, description?, externalDocs?) signature. There is no mention of the
parent / kind fields introduced in OpenAPI 3.2, nor of the object form of @ApiTags.

Issue Number: N/A

What is the new behavior?

The "Tags" section of content/openapi/operations.md now documents:

  • DocumentBuilder.addTag() with the new optional 4th argument for hierarchy options (parent, kind)
  • The object form of @ApiTags({ name, parent?, kind? })
  • Mixing string and object forms
  • A hint clarifying OpenAPI 3.0/3.1 backward compatibility and that hierarchy info is only meaningful at
    the document level

Related feature PR: nestjs/swagger#3725

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

  • Docs updated: content/openapi/operations.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant