Native OpenAPI 3.2.0 Tag Object support (parent, summary, kind, externalDocs)

[jeffreyvanhees]

This PR adds support for the native OpenAPI 3.2.0 Tag Object fields, giving you spec-compliant hierarchical tag grouping plus new metadata fields.

What changed

• Bumped OpenAPI version from 3.1.0 to 3.2.0
• Native parent field
• New summary, kind, externalDocs fields on tags (OAS 3.2.0 spec)
• Auto-creates parent tags when referenced by child tags but not explicitly defined

Usage

Hierarchical grouping with parent

#[Group(name: 'users', parent: 'User Management')]
class UsersController {}

#[Group(name: 'profiles', parent: 'User Management')]
class ProfilesController {}

This generates native parent fields on the tag objects:

{
  "tags": [
    { "name": "users", "parent": "User Management" },
    { "name": "profiles", "parent": "User Management" },
    { "name": "User Management" }
  ]
}

The User Management parent tag is auto-created if you don't define it yourself. If you want to add a description or other metadata to it, define it explicitly on any controller:

#[Group(name: 'User Management', description: 'All user-related endpoints')]
class UserManagementController {}

Tag summary

A short summary, separate from the longer description:

#[Group(name: 'Users', summary: 'User CRUD', description: 'Full user management including registration, profiles, and preferences.')]

Tag kind

Indicate whether a tag is for navigation or represents an API:

#[Group(name: 'Internal', kind: 'api')]

External documentation

Link to external docs for a tag:

#[Group(name: 'Payments', externalDocsUrl: 'https://docs.stripe.com', externalDocsDescription: 'Stripe API reference')]

Generates:

{
  "tags": [{
    "name": "Payments",
    "externalDocs": {
      "url": "https://docs.stripe.com",
      "description": "Stripe API reference"
    }
  }]
}

Combining everything

#[Group(
    name: 'Billing',
    description: 'Invoices, subscriptions and payment methods',
    summary: 'Billing APIs',
    weight: 1,
    parent: 'Commerce',
    kind: 'api',
    externalDocsUrl: 'https://example.com/billing-docs',
    externalDocsDescription: 'Billing developer guide',
)]
class BillingController {}

Breaking changes

• The OpenAPI version is now 3.2.0. Tools that don't support 3.2.0 may not recognize the new tag fields.

Backward compatibility

• All existing #[Group] attributes without parent are unaffected
• New parameters (summary, kind, externalDocsUrl, externalDocsDescription) are all optional

[jeffreyvanhees]

Tests are failing because composer tries to install the oldest compatible versions of dependencies. Recent updates to Pest PHP and its dependencies now require PHP 8.2+ creating a conflict with the PHP 8.1 test configuration.

[romalytvynenko]

@jeffreyvanhees what do you think about how this PR fits/relates to newly introduced OpenAPI 3.2.0 tags that support child/parent relationships?

[jeffreyvanhees]

@jeffreyvanhees what do you think about how this PR fits/relates to newly introduced OpenAPI 3.2.0 tags that support child/parent relationships?

Very nice! I'll update my PR to this when I have time :)