feat(Endpoint): Add title and description attributes to Endpoint attribute

[mikield]

Summary

This PR adds support for title and description parameters to the Endpoint attribute, allowing developers to set custom OpenAPI operation summaries and descriptions directly via the attribute.

Changes Made

1. Enhanced Endpoint Attribute

• File: src/Attributes/Endpoint.php
• Added title and description properties to the Endpoint attribute
• Updated constructor to accept these new parameters
• title maps to OpenAPI summary field
• description maps to OpenAPI description field

2. Updated RequestEssentialsExtension

• File: src/Support/OperationExtensions/RequestEssentialsExtension.php
• Added setTitleAndDescriptionFromEndpointAttribute() method
• Extracts title and description from Endpoint attribute and sets them on the operation
• Integrated into the main extension flow

3. Fixed RequestBodyExtension Override Issue

• File: src/Support/OperationExtensions/RequestBodyExtension.php
• Modified to conditionally set summary and description from PHPDoc comments
• Only sets these values if they haven't already been set by other extensions (e.g., Endpoint attribute)
• This prevents the Endpoint attribute values from being overridden

Usage Examples

Basic Title

#[Endpoint(title: 'Get User Profile')]
public function show(User $user) {
    return $user;
}

Title and Description

#[Endpoint(
    title: 'Create New User',
    description: 'Creates a new user account with the provided information'
)]
public function store(CreateUserRequest $request) {
    // ...
}

Combined with Operation ID

#[Endpoint(
    operationId: 'users.update',
    title: 'Update User',
    description: 'Updates an existing user with new information'
)]
public function update(UpdateUserRequest $request, User $user) {
    // ...
}

Testing

All existing tests continue to pass, and new tests have been added to verify:

• ✅ Title setting via Endpoint attribute
• ✅ Description setting via Endpoint attribute
• ✅ Combined title and description usage
• ✅ Integration with existing operationId functionality
• ✅ Proper precedence where Endpoint attribute values take priority over PHPDoc comments

Technical Details

Extension Execution Order

The fix addresses an issue where RequestBodyExtension was running after RequestEssentialsExtension and unconditionally overriding the operation's summary and description with PHPDoc values. The solution ensures that:

1. RequestEssentialsExtension sets title/description from Endpoint attribute
2. RequestBodyExtension only sets values from PHPDoc if not already set
3. Endpoint attribute values take precedence over PHPDoc comments

OpenAPI Mapping

• Endpoint::$title → OpenAPI summary
• Endpoint::$description → OpenAPI description

This follows OpenAPI 3.0 specification where:

• summary is a short summary of what the operation does
• description is a verbose explanation of the operation behavior

Backward Compatibility

This change is fully backward compatible:

• Existing Endpoint attributes continue to work unchanged
• PHPDoc-based documentation continues to work when Endpoint attributes don't specify title/description
• No breaking changes to existing APIs or functionality

Related Issues

This enhancement improves the developer experience by allowing more granular control over OpenAPI documentation directly through attributes, reducing the need for PHPDoc comments for basic operation metadata.