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 https://github.com/nelmio/NelmioApiDocBundle/blob/a4c4ffcf3bbcc40d10510f026c4b5a757db8c947/OpenApiPhp/Util.php#L372-L379 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 https://github.com/nelmio/NelmioApiDocBundle/pull/2230