fix(openapi): fallback description on summary

[VincentLanglet]

Q	A
Branch?	main for features / current stable version branch for bug fixes
Tickets	Closes #..., closes #...
License	MIT
Doc PR	api-platform/docs#...

When the Summary of an OpenApiResponse is overriden, ApiPlatform still use the default description while it might have no relation with the endpoint/new summary.
I feel like it would be better to fallback on summary instead.

[soyuka]

this will likely break existing apis that rely on the previous behavior no ? :/

[VincentLanglet]

this will likely break existing apis that rely on the previous behavior no ? :/

Yes.

One could argue it's the same than any PR modifying the schema like #7658 or #7832. Depend on if it's seens as a BC break or a fix.

Here, the only change of this PR occurs if

• The user override the summary
• but let null for the description

This will fallback to the getPathDescription pall which does

switch ($method) {
            case 'GET':
                $pathSummary = $isCollection ? 'Retrieves the collection of %s resources.' : 'Retrieves a %s resource.';
                break;
            case 'POST':
                $pathSummary = 'Creates a %s resource.';
                break;
            case 'PATCH':
                $pathSummary = 'Updates the %s resource.';
                break;
            case 'PUT':
                $pathSummary = 'Replaces the %s resource.';
                break;
            case 'DELETE':
                $pathSummary = 'Removes the %s resource.';
                break;
            default:
                return $resourceShortName;
        }

I would find very weird that someone rely on this default behavior.

If you override the summary to have a correct/more precise summary, you won't expect to still have an incorrect/unprecise description.

The main usecase for overriding the summary to me is when developping a custom route and in this case the description need to be overriden too, so it would be useful to defaut to the summary