Render OpenAPI 3.2 Tag Object enhancements (summary, kind, parent)

[frbuceta]

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.2.0
info:
  title: Example
  version: 1.0.0
tags:
  - name: Authentication
    summary: Auth
    description: Identity and access management
    kind: navigation
  - name: Sessions
    description: Sign-in, refresh tokens, active sessions
    parent: Authentication
  - name: API Keys
    description: Long-lived programmatic credentials
    parent: Authentication
paths:
  /auth/sign-in:
    post:
      tags: [Authentication, Sessions]
      responses: { '200': { description: OK } }
  /auth/api-keys:
    get:
      tags: [Authentication, API Keys]
      responses: { '200': { description: OK } }

Swagger-UI configuration options: default.

Is your feature request related to a problem?

OpenAPI 3.2.0 added three new fields to the Tag Object:

• summary — short summary for display
• kind — categorize the tag (nav, badge, audience, …)
• parent — nest a tag under another

PR #10721 ("feat(oas32): add basic OpenAPI 3.2.0 support", merged in v5.32.0) explicitly defers these Tag Object enhancements to a future PR. Quoting the PR description verbatim:

Enhanced Features (moved to future PR):
The following OAS 3.2 features are excluded from this basic implementation and will be addressed in a separate enhancement PR:

• …
• Tag enhancements (summary, kind, parent)
• …

I couldn't find a follow-up issue or PR tracking this work, so opening one so it has a home.

Describe the solution you'd like

Render the new Tag Object fields in the sidebar / operation grouping:

• parent — nest child tag groups visually under their parent. A spec like the one above should produce a tree where Sessions and API Keys appear collapsed under Authentication, instead of three sibling groups.
• summary — when present, display it as the group title (with description still rendered below as Markdown). Falls back to name if missing.
• kind — a machine-readable category hint. Common values per the spec: nav (navigation-only, no operations expected), badge (visible badge), audience (e.g. partner, external). At minimum, treating nav / navigation differently (e.g. allowing a tag group with zero operations to still render as a navigation node) would unblock the hierarchy use case described above.

Tooling that produces these specs already exists — for example @nestjs/swagger 11.4.0 supports emitting parent/kind via DocumentBuilder.addTag(). Spec is correct end-to-end today; the bottleneck is the renderer.

Describe alternatives you've considered

• Naming convention ("Authentication / Sessions") — works, but loses the structured parent data that 3.2 introduced specifically to avoid this workaround.
• The 2021 community plugin (PR #7039) — predates OAS 3.2 and parses a delimiter in the tag name; it doesn't read the new fields.
• Switching renderer (Redoc / Scalar / Elements) — each has its own gaps; staying on Swagger UI is preferable for projects already using it.

Additional context

Related:

• OAS 3.2.0 spec: https://spec.openapis.org/oas/v3.2.0.html#tag-object
• Merged basic 3.2 PR: feat(oas32): add basic OpenAPI 3.2.0 support #10721
• Original meta-issue for 3.2 support: Support OpenAPI 3.2 #10575
• Older hierarchical-tags plugin (pre-3.2): feat: basic hierarchical-tags plugin #7039 / Implement Hierarchical Tags #7050

Happy to help test or contribute once direction is decided.