Is the schemas section in the nelmio_api_doc.yaml required?

Question

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.

Guilhem N Guilhem N · Accepted Answer · 2020-08-15T14:18:02

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))
     *        )
     *     )
     */

Is the schemas section in the nelmio_api_doc.yaml required?

1 Answers