Allow custom key usage in "documentation" (for example x-logo)

[BafS]

It's currently not possible to use a custom key (x-...), it can be useful for some frontends, for example Redoc uses x-logo.

Example:

nelmio_api_doc:
    documentation:
        x-logo: # <- not possible
            url: 'https://redocly.github.io/redoc/petstore-logo.png'
            altText: Petstore logo
        info:
            title: My API

"Undefined index: x_logo"

exception | "ErrorException"
file | "/.../api/vendor/nelmio/api-doc-bundle/OpenApiPhp/Util.php"
line | 377

[GuilhemN]

Indeed, zircote/swagger-php annotations support custom keys through the x field (see https://github.com/zircote/swagger-php/blob/a824f77936558c27d2ca43d00528f505fb12f9e3/src/Annotations/AbstractAnnotation.php#L22-L29).

As pointed by the error you provided, we should update

NelmioApiDocBundle/OpenApiPhp/Util.php

Lines 372 to 379 in a4c4ffc

	foreach ($properties as $propertyName => $value) {
	if ('$ref' === $propertyName) {
	$propertyName = 'ref';
	}
	if (!\in_array($propertyName, $done, true)) {
	self::mergeProperty($annotation, $propertyName, $value, $defaults[$propertyName], $overwrite);
	}
	}

to recognize fields beginning with x-.

[BafS]

Note: it's possible to do

nelmio_api_doc:
    documentation:
        x:
            logo:
                url: 'https://....png'
                altText: Petstore logo
...

I don't know what you prefer, in any case it would be good to document it :)

[GuilhemN]

I'm not fund of using documentation.x, this does not respect the swagger specification and thus prevent people from using existing documentations.

[DjordyKoert]

Fixed in #2230