Swagger-php: @OA\Schema can no longer be nested in itself

Created on 31 Aug 2020 · 6Comments · Source: zircote/swagger-php

I recently upgraded from 3.0.4 to 3.0.5 and a change must have broken some functionality I'm relying on for my API definitions. Consider the Inheritance and Polymorphism page's Model Composition section, it's basically what I'm doing here:

/**
 * @OA\Schema(
 *   schema="PublicUser",
 *   type="object",
 *   description="Represents a publicly accessible representation of a user",
 *   required={
 *     "id",
 *     "name",
 *     "avatarUrl",
 *   },
 *   additionalProperties=false,
 *   @OA\Property(
 *     property="id",
 *     type="integer",
 *     minimum=1,
 *     example=1,
 *   ),
 *   @OA\Property(
 *     property="name",
 *     type="string",
 *     example="example",
 *   ),
 *   @OA\Property(
 *     property="avatarUrl",
 *     type="string",
 *     format="uri",
 *     example="https://a.deviantart.net/avatars/e/x/example.png",
 *     nullable=true,
 *   ),
 * )
 */
/**
 * @OA\Schema(
 *   schema="User",
 *   allOf={
 *     @OA\Schema(ref="#/components/schemas/PublicUser"),
 *     @OA\Schema(
 *       type="object",
 *       description="Represents an authenticated user",
 *       required={
 *         "email",
 *         "role",
 *       },
 *       additionalProperties=false,
 *       @OA\Property(
 *         property="email",
 *         type="string",
 *         example="[email protected]",
 *         nullable=true,
 *       ),
 *     )
 *   }
 * )
 */

This causes an error while generating the docs, which states (formatting mine):

Unexpected @OA\Schema(), expected to be inside @OA\Components, @OA\Parameter, @OA\MediaType, @OA\Header

This works well with 3.0.4 and according to the OpenAPI docs should continue to do so as it's an intended way to achieve this DRY schema. For now I downgraded back to that version so I don't need an urgent response but wanted to file this as an issue to make sure you are aware.

Source

SeinopSys

👍3

Most helpful comment

Will be fixed in the next release.

bfanger on 6 Sep 2020

🎉2

All 6 comments

Your example above in itself seems to be fine - at least it parses fine on master.
Would you be able to create a small demo repo that shows the bad behavior?

DerManoMann on 1 Sep 2020

I have attempted a repro and indeed in a stripped down basic repo could not get the issue to happen again, chances are my issue is elsewhere. Sorry for the trouble.

SeinopSys on 1 Sep 2020

For anyone looking at this issue in the future, it looks like combining the two comments solved the issue in my case. This is one of those "it works but I have no idea why" cases.

The project where this issue was happening is open source, this is the commit that fixes it: https://github.com/MLP-VectorClub/Luna/commit/be7967d04558637fb3a526ffa63a42b3d6e098ca

I couldn't reliably reproduce this issue with just this package installed, so there is a chance some other component in-between is meddling with the definitions and that's tripping it up.

Also including the full error output for search indexers' sake:

$ php artisan l5-swagger:generate
Regenerating docs

   ErrorException 

  Unexpected @OA\Schema(), expected to be inside @OA\Components, @OA\Parameter, @OA\MediaType, @OA\Header in <...>/app/Http/Controllers/UsersController.php on line 58

  at vendor/zircote/swagger-php/src/Logger.php:39
    35|         $this->log = function ($entry, $type) {
    36|             if ($entry instanceof Exception) {
    37|                 $entry = $entry->getMessage();
    38|             }
  > 39|             trigger_error($entry, $type);
    40|         };
    41|     }
    42| 
    43|     /**

      +24 vendor frames 
  25  artisan:37
      Illuminate\Foundation\Console\Kernel::handle()

SeinopSys on 1 Sep 2020

@DerManoMann I'm experiencing the same problem. Here's a link to a repository to reproduce the issue https://github.com/brpauwels/swagger-php-835