[SOLVED] Is the schemas section in the nelmio_api

Is the schemas section in the nelmio_api_doc.yaml required?

I have been setting up the Nelmio API Doc Bundle with Swagger-PHP. All is working as expected the only thing I cannot seem to figure out/understand is the schemas.

In the User controller I have the following annotation:

     *     @OA\RequestBody(
     *         description="Updated user object",
     *         required=true,
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref="#/components/schemas/User")
     *        )
     *     )

In my Entity/User class I defined the schema as follows:

/**
 * User
 *
 * @OA\Schema(schema="User")
 *
 * @ORM\Table(schema="app", name="users")
 * @ORM\Entity
 */
class User implements UserInterface

In the User controller I have the use App\Entity\User; defined as well.

In my mind this would be enough for the schema to be found but it doesn't work as I would otherwise not be posting here :)

The only way I was able to make it work is to run vendor/bin/openapi --format yaml src and copy/paste the schema output into the nelmio_api_doc.yaml file. This is the schema part I copy/pasted:

        User:
          properties:
            first_name:
              type: string
            middle_name:
              type: string
            last_name:
              type: string
            initials:
              type: string
            username:
              type: string
            password:
              type: string
            status:
              type: integer
            email:
              type: string
            id:
              type: integer
            customer_id:
              type: integer
            locked:
              type: boolean
          type: object

So my question is, is this the way to about it or should the schema section be created automatically?

Thanks for any insights.

Solution

NelmioApiDocBundle does not load all files to fetch annotations in opposition to swagger-php, to load a schema, you should use the @Model annotation, see https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#use-models.

In your case, that would give the following:

use Nelmio\ApiDocBundle\Annotation\Model;

     /**
     *     @OA\RequestBody(
     *         description="Updated user object",
     *         required=true,
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref=@Model(type=User::class))
     *        )
     *     )
     */