Skip to content

feat(swagger): add summary field to Tag Object (OpenAPI 3.2)#3921

Merged
kamilmysliwiec merged 1 commit into
nestjs:masterfrom
frbuceta:feat/openapi-32-tag-summary
May 20, 2026
Merged

feat(swagger): add summary field to Tag Object (OpenAPI 3.2)#3921
kamilmysliwiec merged 1 commit into
nestjs:masterfrom
frbuceta:feat/openapi-32-tag-summary

Conversation

@frbuceta

Copy link
Copy Markdown
Contributor

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
  • CI related changes
  • Other... Please describe:

What is the current behavior?

OpenAPI 3.2 added three new fields to the Tag Object: parent, kind, and summary. PR #3725 added support for parent and kind, but summary was not included.

Per the OpenAPI 3.2 spec:

summary | string | A short summary of the tag, used for display purposes.

What is the new behavior?

  • TagObject interface now includes optional summary field.
  • DocumentBuilder.addTag() accepts summary in its 4th-parameter options object, alongside the existing parent and kind.
const config = new DocumentBuilder()
  .addTag('account-updates', 'Account update operations', undefined, {
    summary: 'Account Updates'
  })
  .build();

ApiTagOptions and the @ApiTags() decorator are intentionally not extended in this PR — their hierarchy metadata (parent/kind) is currently discarded (see the existing tests in test/decorators/api-use-tags.decorator.spec.ts which assert this). I'll open a separate issue for that so it can be discussed independently.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

Refs #3725.

@kamilmysliwiec

Copy link
Copy Markdown
Member

@copilot resolve the merge conflicts in this pull request

OpenAPI 3.2 introduced three new fields on the Tag Object: parent,
kind, and summary. PR nestjs#3725 added parent and kind support, but summary
was omitted. This change adds it to the TagObject interface and
exposes it via DocumentBuilder.addTag() options, matching the surface
area of the existing hierarchy options.

Per the spec, summary is "a short summary of the tag, used for display
purposes" (https://spec.openapis.org/oas/v3.2.0.html#tag-object).
@frbuceta frbuceta force-pushed the feat/openapi-32-tag-summary branch from 509d41c to 5dd7ce3 Compare May 20, 2026 09:23
@frbuceta

Copy link
Copy Markdown
Contributor Author

@copilot resolve the merge conflicts in this pull request

I've already updated it for you. Thanks

@kamilmysliwiec kamilmysliwiec merged commit 8121be3 into nestjs:master May 20, 2026
1 check passed
@kamilmysliwiec

Copy link
Copy Markdown
Member

lgtm

@frbuceta frbuceta deleted the feat/openapi-32-tag-summary branch May 20, 2026 09:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants