Search code examples
phpswaggerlaravel-8swagger-php

l5-swagger/swagger-php support for x-logo within the OpenAPI (3.0.1) in the @OA\Info block (for Laravel 8)

I am using l5-swagger and redocly to display API documentation for a Laravel 8 project.

Open API supports:

"x-logo": {
        "url": "path_to_your_logo"
    },

I have tried:

@OA\X_Logo
@OA\XLogo
@OA\Logo

But I cannot find any mention within l5-swagger on how to mark-up the logo within the comments on the Controller in order for the logo markup above to be generated when running

php artisan l5-swagger:generate

I also cannot find anyone asking this question which seems odd because surely this is a common query to come up?

So I am leaning towards that it isn't currently supported in swagger-php

Searching here for Info/Logo returns no mention of Logo and again searching here for Info/Logo returns no mention of Logo

Which then makes this a question of how could it be done - it surely would be that difficult to introduce support for it.

So I have tried with this pull-request on swagger-php so that I can then get support added to l5-swagger.

Any help with this would be appreciated, I apologise if this has been asked before! But hopefully we can get it answered and then this will be a question/answer worth having.

EDIT / UPDATE

Thank you @bob-fanger for the correct answer.

It turns out that the x-logo is not part of the OpenAPI spec so probably this is outside of the scope of this library. But that doens't matter as Bob has explained that l5-swagger does support it.

I will try to get a logo example added to their documentation to make it easier to find for everyone going forward.

Solution

  • x- properties are supported in swagger-php, those properties are not part of the openapi spec and are referred to as vendor extensions.

    https://zircote.github.io/swagger-php/Getting-started.html#vendor-extensions

    /**
 * @OA\Info(
 *   title="Example",
 *   version="1.0.0",
 *   x={
 *     "logo": {
 *       "url": "path_to_your_logo"
 *     }
 *   }
 * )
 */

    will generate:

    openapi: 3.0.0
info:
  title: Example
  version: 1.0.0
  x-logo:
    url: path_to_your_logo