Is the schemas section in the nelmio_api_doc.yaml required? - swagger-php

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.

Answer 1

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