l5-swagger/swagger-php - adding component to block makes it dissapear from the output

If I add this response to my definition:

@OA\Response(
    response="default",
    description="unexpected error",
    @OA\JsonContent(ref="#/components/schemas/ErrorModel"),
    @OA\XmlContent(ref="#/components/schemas/ErrorModel"),
    @OA\MediaType(
        mediaType="text/xml",
        @OA\Schema(ref="#/components/schemas/ErrorModel")
        ),
        @OA\MediaType(
          mediaType="text/html",
          @OA\Schema(ref="#/components/schemas/ErrorModel")
        )
 )

And then I place the Schema underneath like so:

/**
 * @OA\Schema(
 *     schema="ErrorModel",
 *     required={"code", "message"},
 *     @OA\Property(
 *         property="code",
 *         type="integer",
 *         format="int32"
 *     ),
 *     @OA\Property(
 *         property="message",
 *         type="string"
 *     )
 * )
 */

The command: php artisan l5-swagger:generate does not error but the block that contains the Response Definition with the component no longer gets included in the json but the schema for the component does?

Did I do something really obvious that is wrong as my experience with the library so far is if you do something wrong it generally tells you.

Solution

If this is a new projects changes are that you are now using swagger-php V4. In version 4 the analyser code uses reflection. This was done to make it possible to use either annotations or PHP 8 attributes.

One downside is that stand-alone docblocks are no longer detected as there is no reflection to access those.

In your case I think having two separate blocks of /** */ will mean only the last one is found.

One way around is to have all annotations preceding a class in a single /** */ block. Another option is to have (unused) dummy classes for cases like this.

Here, adding class ErrorModel {} fater your schema should work too, assuming there is a separate resonse class for the first annotation.

The same applies to other top level annotations like @OA\Info or others.