Swagger-php: How do I create an array of objects, showing multiple to convey that it will accept multiple

[faithfulman18]

I'm trying to show in my swagger that I'm expecting multiple records of the same object in an array, but I'm not certain how to make it happen. I'm trying to get the following to show up in my request body:

{
  "testUsers": [
    {
      "firstName": "",
      "lastName": "",
      "company": "",
      "id": "",
    },
    {
      "firstName": "",
      "lastName": "",
      "company": "",
      "id": ""
    }
  ]
}

I've tried a number of things like this, to no avail:

   /**
     * @OA\POST(
     *     path="/api/testing/v1/tester/testUsers",
     *     summary="Create a Test",
     *     tags={"TEST"},
     *     @OA\RequestBody(
     *        required = true,
     *        description = "Data packet for Test",
     *        @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                property="testItems",
     *                type="array",
     *                @OA\Items(
     *                      @OA\Property(
     *                         property="firstName",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="lastName",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="companyId",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="accountNumber",
     *                         type="number",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="netPay",
     *                         type="money",
     *                         example=""
     *                      ),
     *                ),
     *                @OA\Items(
     *                      @OA\Property(
     *                         property="firstName",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="lastName",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="companyId",
     *                         type="string",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="accountNumber",
     *                         type="number",
     *                         example=""
     *                      ),
     *                      @OA\Property(
     *                         property="netPay",
     *                         type="money",
     *                         example=""
     *                      ),
     *                ),

     *             ),
     *        ),
     *     ),
     *
     *
     *     @OA\Response(
     *        response="200",
     *        description="Successful response",
     *     ),
     * )
     */

What am I missing?

[bfanger]

The testItems is of type array, a single OA\Items() annotation is needed to describe the contents of the array. This is enough to show that the api accepts multiple items, swagger-ui might show a single item as an example but as far as documenting that you'll except multiple records, you're done.

If you want to document that the array must contain a minimum or maximum number of items that's also possible.

You can also overwrite an example value for testItems and provide an array with 2 items. (Arrays are also written with { and } as delimiters)

[faithfulman18]

Can you provide an example of what you mean by overriding an example value? Also, how would I say that multiple were required?

[bfanger]

A @OA\Property is a OpenAPI Schema which is based on JSON Schema with has maxItems and maxItems

To provide example data use example=, for example:

/**
 * @OA\POST(
 *     path="/api/testing/v1/tester/testUsers",
 *     summary="Create a Test",
 *     tags={"TEST"},
 *     @OA\RequestBody(
 *        required = true,
 *        description = "Data packet for Test",
 *        @OA\JsonContent(
 *             type="object",
 *             @OA\Property(
 *                property="testItems",
 *                type="array",
 *                example={{
 *                  "firstName": "Bob",
 *                  "lastName": "Fanger",
 *                  "company": "Triple",
 *                  "id": "808",
 *                }, {
 *                  "firstName": "",
 *                  "lastName": "",
 *                  "company": "",
 *                  "id": ""
 *                }},
 *                @OA\Items(
 *                      @OA\Property(
 *                         property="firstName",
 *                         type="string",
 *                         example=""
 *                      ),
 *                      @OA\Property(
 *                         property="lastName",
 *                         type="string",
 *                         example=""
 *                      ),
 *                      @OA\Property(
 *                         property="companyId",
 *                         type="string",
 *                         example=""
 *                      ),
 *                      @OA\Property(
 *                         property="accountNumber",
 *                         type="number",
 *                         example=""
 *                      ),
 *                      @OA\Property(
 *                         property="netPay",
 *                         type="money",
 *                         example=""
 *                      ),
 *                ),
 *             ),
 *        ),
 *     ),
 *
 *
 *     @OA\Response(
 *        response="200",
 *        description="Successful response",
 *     ),
 * )
 */

[faithfulman18]

Thanks!! This is exactly what I needed.

[appetize-api]

Hi there,

I am trying to add more than one example response under the same status code. OA3 supports this as:

      responses:
        200:
          description: Success Responses
          content:
            application/json:
              examples:
                'Empty Response':
                  value:
                    []
                'Success Response':
                  value: >-
                     { "foo": "bar"}

Any way to do that with the @OA decorators under the same status code?

[Bujhm]

@appetize-api
i've made something like that (maybe it will be helpful):

     * @OA\Response(
     *     response=200,
     *     description="Return one of these result strings (u can put value: "value" into { } ,
     *  so u will get json array in the output window as is the example with index 0: ",
     *     @OA\JsonContent(
     *              type="object",
     *              examples={
     *                    0: {
     *                          "summary": "success",
     *                          "value": {"ok"} },
     *                    1: {
     *                          "summary": "error 1",
     *                         "value": "error1 - something"
     *                     },
     *                    2: {
     *                          "summary": "error 2",
     *                          "value": "error 2 - something"
     *                    },
     *                    3: {
     *                         "summary": "error 3",
     *                          "value": "error 3 - something"
     *                    },
     *             }
     *      )
     *  )`