L5 Swagger - how to add examples for request body or response body

Question

i'm trying to define some request body example in a file and link this file to the actual request, i saw we can use Swagger $ref to do that Reusing Examples but i can't find the correct L5 Swagger syntax to do it please any help.

my code:

/**
 * @OA\Post(
 *     operationId="vehicleStore",
 *     tags={"vehicle"},
 *     summary="Store Vehicle - with components and trips (damages & loads)",
 *     description="Store vehicle",
 *     path="/vehicle",
 *     security={{"bearerAuth":{}}},
 *
 *     @OA\RequestBody(
 *       @OA\JsonContent(
 *          allOf={
 *                    @OA\Schema(ref="#/components/schemas/APIResponse"),
 *                    @OA\Schema(ref="#/components/schemas/CustomResponse")
 *               },
 *              examples={ @OA\Examples( externalValue="http://api.nytimes.com/svc/search/v2/articlesearch.json", summary="1" ) }
 *          )
 *      ),
 *
 *     @OA\Response(
 *         response="200",
 *         description="Successful",
 *          @OA\JsonContent()
 *      ),
 * )
 *
 * @return JsonResponse
 *
 */

i'm trying to use @OA\Examples please if any one can do an example of how we can us it, that will be great

update

i tried something like

/**
 *
 *      @OA\Examples(
 *        summary="VehicleStore",
 *        example = "VehicleStore",
 *       value = {
 *              "result": null,
 *              "message": "Unauthorized, you don't have access to this content, Invalid token.",
 *              "status": 401
 *         },
 *      )
 */

then

    /**
 * @OA\Post(
 *     operationId="vehicleStore",
 *     tags={"vehicle"},
 *     summary="Store Vehicle - with components and trips (damages & loads)",
 *     description="Store vehicle",
 *     path="/vehicle",
 *     security={{"bearerAuth":{}}},
 *
 *     @OA\RequestBody(
 *       @OA\JsonContent(
 *               allOf={
 *                      @OA\Schema(ref="#/components/schemas/APIResponse"),
 *                      @OA\Schema(ref="#/components/schemas/CustomRequestBody")
 *              },
*       examples = {
 *          @OA\Schema( ref="#/components/examples/VehicleStore")
    *
 *     }
 *
 *          )
 *      ),
 *
 *     @OA\Response(
 *         response="200",
 *         description="Successful",
 *          @OA\JsonContent()
 *      ),
 * )
 *
 * @return JsonResponse
 *
 */

in the ui its show example: VehicleStore but the Example Value still empty in the ui

Answer 1

i found the correct L5 syntax to do multiple examples with using refs also :

so first i define the examples as:

/**
 *      @OA\Examples(
 *        summary="VehicleStoreEx1",
 *        example = "VehicleStoreEx1",
 *       value = {
*           "name": "vehicle 1"
*         },
*      )
*/

/**
 *      @OA\Examples(
 *        summary="VehicleStoreEx2",
 *        example = "VehicleStoreEx2",
 *       value = {
 *              "name": "vehicle 1",
 *              "model": "Tesla"
 *         },
 *      )
 */

then i defined a request body because i need multiple examples for one request i think the same thing can be done to a response also if any one need response with multiple examples so my request body was:

/**
 * @OA\RequestBody(
 *     request="VehicleStoreRequestBody",
 *     description="Pet object that needs to be added to the store",
 *     required=true,
 *     @OA\JsonContent(
 *        allOf={
 *           @OA\Schema(ref="#/components/schemas/APIResponse"),
 *           @OA\Schema(ref="#/components/schemas/CustomRequestBody")
 *        },
 *       examples = {
 *          "example_1" : @OA\Schema( ref="#/components/examples/VehicleStoreEx1"),
 *          "example_2" : @OA\Schema( ref="#/components/examples/VehicleStoreEx2"),
 *      }
 *    )
 * )
 */

then i linked the request body to the request as:

/**
* @OA\Post(
 *     operationId="vehicleStore",
 *     tags={"vehicle"},
 *     summary="Store Vehicle - with components and trips (damages & loads)",
 *     description="Store vehicle",
 *     path="/vehicle",
 *     security={{"bearerAuth":{}}},
 *    requestBody={"$ref": "#/components/requestBodies/VehicleStoreRequestBody"},
*     @OA\Response(
 *         response="200",
 *         description="Successful",
 *          @OA\JsonContent()
 *      ),
 * )
 *
 * @return JsonResponse
*
 */

and that generated the flowing objects in api-docs.json

        "examples": {
            "VehicleStoreEx1": {
                "summary": "VehicleStoreEx1",
                "value": {
                    "name": "vehicle 1"
                }
            },
            "VehicleStoreEx2": {
                "summary": "VehicleStoreEx2",
                "value": {
                    "name": "vehicle 1",
                    "model": "Tesla"
                }
            }
        },
        "requestBodies": {
            "VehicleStoreRequestBody": {
                "description": "Pet object that needs to be added to the store",
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/components/schemas/APIResponse"
                                },
                                {
                                    "$ref": "#/components/schemas/CustomRequestBody"
                                }
                            ]
                        },
                        "examples": {
                            "example_1": {
                                "$ref": "#/components/examples/VehicleStoreEx1"
                            },
                            "example_2": {
                                "$ref": "#/components/examples/VehicleStoreEx2"
                            }
                        }
                    }
                }
            }
        },

hope this will help any one searching how to do response or request with multiple examples

Answer 2

Thanks @Fadi for the pointers. Your answer helped me a lot in figuring out how to get this to work. To get it running with zircote/swagger-php 3.2.3 i needed to fiddle around a bit:

     * @OA\Examples(
     *     example="RequestExample",
     *     summary="An example request",
     *     value={
     *         "json": {
     *             "structure": "with stuff"
     *         }
     *         "arrays": {
     *             {
     *                 "are": "given as"
     *             },
     *             {
     *                  "objects": "for some reason"
     *             }
     *         }
     *     }
     * )
     *      
     * @OA\Post(
     *     path="/my-path",
     *     tags={"MyTag"},
     *     @OA\RequestBody(
     *         required=true,
     *         description="Request Body Description",
     *         @OA\JsonContent(
     *             ref="#/components/schemas/MyRequestSchema",
     *             examples={
     *                 "myname": @OA\Schema(ref="#/components/examples/RequestExample", example="RequestExample"),
     *             },
     *         ),
     *     ),

I needed to add example to the example definition to define the key i can reference. I also had to add an example key in the @OA\Schema, no idea why or what that one does. But without it, i got User Warning: @OA\Schema() is missing key-field: "example"

As our requests are JSON, we have a complex structure in the example value. It works, but I had to use {} for arrays, as [] leads to an error Expected PlainValue, got '['. Somehow things are then output correctly as array.