Swagger PHP - how to define a nested property?

hyarion picture hyarion · May 20, 2016 · Viewed 10.3k times · Source

I'm using Swagger PHP and most of the definitions are easy to define, but I'm having an issue with a particular piece of data that is not part of a seperate class, but instead an associative array.

The json response I wish to show (simplified for this question):

{
"id": 1,
"status": "published",
"gps": {
    "lat": "0.00000000",
    "lng": "0.00000000"
}

The id and status are easy enough to define, however the gps is a problem as there is no seperate class to define it in, it is an array inside the model. Is it possible to define this array without having to create a dummy class?

The comments in the model file currently:

/**
 * @SWG\Definition(@SWG\Xml(name="Event"))
 */
 class Event extends BaseModel {
     /**
     * @SWG\Property(
     *      property="id",
     *      type="integer",
     *      example="103"
     * )
     * @SWG\Property(
     *      property="status",
     *      type="string",
     *      enum={"published", "draft", "suspended"}
     *      example="published"
     * )
     */

 }

Answer

JDpawar picture JDpawar · Aug 17, 2016

Faced the exact same issue, and resolved it today!

This is for Swagger 2.0

Following is the annotation nesting that I have used to achieve the nested parameters..

/**
 * @SWG\Post(
 *   path="/getCustomerByEmail.php",
 *   summary="List the details of customer by the email.",
 *   consumes={"string"},
 *   produces={"application/json"},
 *   @SWG\Parameter(
 *     name="email",
 *     in="body",
 *     description="Customer email to ge the data",
 *     required=true,
 *     @SWG\Schema(
 *       @SWG\Property(
 *         property="id",
 *         type="object",
 *         @SWG\Property(
 *           property="abc",
 *           type="object",
 *           @SWG\Property(
 *             property="inner abc",
 *             type="number",
 *             default=1,
 *             example=123
 *           )
 *         ),
 *         @SWG\Property(
 *           property="xyz",
 *           type="string",
 *           default="xyz default value",
 *           example="xyz example value",
 *         )
 *       )
 *     )
 *   ),
 *   @SWG\Response(
 *     response=200,
 *     description="Details of the customer"
 *   ),
 *   @SWG\Response(
 *     response=400,
 *     description="Email required"
 *   ),
 *   @SWG\Response(
 *     response=404,
 *     description="Customer does not exist"
 *   ),
 *   @SWG\Response(
 *     response="default",
 *     description="an ""unexpected"" error"
 *   )
 * )
 */
/**

The output is as below

Note: I was working on a project which required raw PHP but still wanted to use Swagger. So instead of creating the models, I used this technique to make the nested parameters.


Edit 1: I don't know what's the problem, UI is as expected but while making the request, there is no data in the post or the payload.

Edit 2: Converted Get to Post. Works fine with file_get_contents("php://input")