Nelmioapidocbundle: Object within object in response

[Joozty]

I'm using NelmioApiDocBundle and Swagger to describe my API.

I want to describe my response object that contains another object:

For example - json str:

"Person": {
    "firstname": "John",
    "lastName": "Smith",
    "car": {
       "brand": "Tesla",
       "price": "1000"
    }
}

My PHP look like:

use Swagger\Annotations as SWG;

class Person {

    /**
     * @SWG\Property(
     *     title="firstName",
     *     type="string",
     *     required={"true"},
     *     description="Last Name"
     * )
     */
    protected $firstName;
    /**
     * @SWG\Property(
     *     title="lastName",
     *     type="string",
     *     required={"true"},
     *     description="First Name"
     * )
     */
    protected $lastName;        
    /**
     * @SWG\Property(
     *     title="data",
     *     required={"true"},
     *     description="The fetched article",
     *     type="object", <- THAT IS THE PROBLEM
     *     @SWG\Property(property="Car", type=Car::class)
     * )
     */
    protected $car;
}

class Car {

    /**
     * @SWG\Property(
     *     title="brand",
     *     type="string",
     *     required={"true"},
     *     description="brand"
     * )
     */
    protected $brand;
    /**
     * @SWG\Property(
     *     title="price",
     *     type="string",
     *     required={"true"},
     *     description="price"
     * )
     */
     protected $price;

}

Configuration:

• php: "7.1.7"
• nelmio/api-doc-bundle: "3.0"
• symfony/symfony: "3.4.0",
• zircote/swagger-php": "2.0"

How can I do that?

Thanks a lot.

[GuilhemN]

This will be allowed by https://github.com/nelmio/NelmioApiDocBundle/pull/1263 (see https://github.com/nelmio/NelmioApiDocBundle/pull/1263/files#diff-fdd764ee72f777e180ace83412a44158R270)

[GuilhemN]

Okay in fact I misunderstood your issue, you don't even need #1263, just add a type hint to your property so that the bundle knows it's an instance of Car (@Type if you're using the jms serializer).

[Joozty]

@GuilhemN Could you please help me how can I achieve this.

You mean something like this:

    /**
     * @SWG\Property(
     *     title="car",
     *     description="car",
     *     type="object",
     *     @JMS\Type("path_to_car\Car")
     * )
     */
     protected $car;

Thanks in advance

[GuilhemN]

I mean:

    /**
     * @JMS\Type("path_to_car\Car")
     */
     protected $car;

The bundle will then detect your property's type.

[Joozty]

@GuilhemN Thank you, it helped :)

[dbu]

thought its open and did not read the button caption. glad this is solved again :-)

[Joozty]

@GuilhemN @dbu Sorry, one more question comes to my mind. What about array of object?

"Person": {
    "firstname": "John",
    "lastName": "Smith",
    "car": [
       {
           "brand": "Tesla",
           "price": "1000"
       },
       {
           "brand": "Mercedes",
           "price": "5000"
       }
    ]
}

This doesn't work:

/**
 * @SWG\Property(
 *     title="car",
 *     description="car",
 *     type="array",
 *     items=@SWG\Items("Car::class")
 * )
*/
protected $car;

[GuilhemN]

Just use @JMS\Type as well:
@JMS\Type('array<App\Entity\Car>')

(If you prefer using @SWG\Property, you'll have to wait for https://github.com/nelmio/NelmioApiDocBundle/pull/1263 and to use @Model)