Nelmioapidocbundle: @SWG\Property with Model annotation

[wbrframe]

Is it possible with the SWG\Property annotation describe object instead of array?

---

Case:

 *     @SWG\Response(
 *         response="400",
 *         description="Bad form data",
 *         @SWG\Schema(
 *             @SWG\Property(property="code", type="integer"),
 *             @SWG\Property(property="messages",
 *                @API\Model(type=PerformerMaster::class, groups={"error"})
 *             )
 *        )
 *     )

After render API docs I see

But I expected to see:

I would be grateful if you could help me!

[kubaceg]

Try this definition

 *     @SWG\Response(
 *         response="400",
 *         description="Bad form data",
 *         @SWG\Schema(
 *             @SWG\Property(property="code", type="integer"),
 *             @SWG\Property(property="messages",
 *                type="object",
 *                @API\Model(type=PerformerMaster::class, groups={"error"})
 *             )
 *        )
 *     )

[wbrframe]

@kubaceg thanks for your answer!
Before asking a question, I've already tried to use this definition.
In this case I get an empty object for messages ((

[GuilhemN]

Could you provide us the swagger file you get please ? (You can have it in json by calling /api/doc.json)

[HermanBilous]

I have the same issue. I debugged the code a little. As far as I can tell, the ModelRegister::__invoke will detect Model being nested in Property and because Property is instanceof Schema it will create an Items with a reference to definition provided in Model.

[GuilhemN]

@ball00n- I don't think that's the case, the ModelRegister checks if the annotation is a Parameter instance before checking if it's a Schema (see https://github.com/nelmio/NelmioApiDocBundle/blob/master/SwaggerPhp/ModelRegister.php#L45).

[HermanBilous]

@GuilhemN yeah, you a correct, it checks if it's a Parameter, but we have an issue with Property.

[GuilhemN]

Indeed sorry, I guess we need to add a new case then to handle Property. Could one of you submit a PR with a test ?

[HermanBilous]

Right now I'm not sure what would be expected result, and how it should work. Perfect solution would be the one that will allow me to create docs for object like

{
    "data": {
        "param": type
    }
}

as well as objects like

{
    "data": [
        {"param": type},
        {"param": type},
    ]
}

How I see the annotation for the first result

 *     @SWG\Response(
 *         response="400",
 *         description="Bad form data",
 *         @SWG\Schema(
 *             @SWG\Property(property="code", type="integer"),
 *             @SWG\Property(property="messages",
 *                @API\Model(type=PerformerMaster::class, groups={"error"})
 *             )
 *        )
 *     )

and annotation for the second

 *     @SWG\Response(
 *         response="400",
 *         description="Bad form data",
 *         @SWG\Schema(
 *             @SWG\Property(property="code", type="integer"),
 *             @SWG\Property(property="messages",
 *                @SWG\Items(
 *                    @API\Model(type=PerformerMaster::class, groups={"error"})
 *                )
 *             )
 *        )
 *     )

Please, share your thoughts

[GuilhemN]

Your second example is not very consistent with the rest of our code imo. I'd rather just differenciate the two with type="array".

[HermanBilous]

Understandable. But I think that if you really don't want to introduce a BC you should differenciate the first one with type="object", as @kubaceg proposed.

[GuilhemN]

Here that's rather a bug imo. I don't think people expect this result.

[GuilhemN]

Thinking of it again, I'm not sure what to do... Since Property is an instance of @Schema it would be weird imo to behave differently.
What do you think about adding a property field to the @Model annotation?

[GuilhemN]

Please have a look at https://github.com/nelmio/NelmioApiDocBundle/pull/1261, it should nicely fix this PR.

[GuilhemN]

https://github.com/nelmio/NelmioApiDocBundle/pull/1261 is merged 🎉

[HermanBilous]

Hey! Great job, you fixed it in a way I wouldn't even think of myself. Thanks!

[shubaivan]

• @SWG\Response(
• response="400",
• description="Bad form data",
• @SWG\Schema(
• @SWGProperty(property="code", type="integer"),
• @SWGProperty(property="messages",
• @APIModel(type=PerformerMaster::class, groups={"error"})
• )
• )
• )

still array messages

{
  "code": 0,
  "messages": [
    {
      "id": 0,
      "name": "string",
    }
  ]
}

Looks like issue actual

[migster42]

I fixed it by placing ref before @Model:

@SWG\Property( property="name", ref=@Model(type=App\Entity\ClassName::class) )