L5 Swagger -如何为请求体或响应体添加示例

Question

我试图在一个文件中定义一些请求正文示例，并将这个文件链接到实际的请求中，我看到我们可以使用Swagger $ref来执行重用示例，但是我找不到正确的L5 Swagger语法来执行它，请提供任何帮助。

我的代码：

/**
 * @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
 *
 */

我正在尝试使用@OA\Examples，如果有人能给我们举一个例子，那就太好了

更新

我试过

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

然后

    /**
 * @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
 *
 */

在ui中，它的演示示例是: VehicleStore，但是ui中的Example Value仍然是空的。

​

​

Answer 1

我找到了正确的L5语法，可以通过使用参考文献来执行多个示例：

首先，我将这些例子定义为：

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

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

然后，我定义了一个请求体，因为我需要一个请求的多个例子，我认为对一个响应可以做同样的事情，如果任何一个人需要用多个例子进行响应，那么我的请求体是：

/**
 * @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"),
 *      }
 *    )
 * )
 */

然后，我将请求主体与请求链接为：

/**
* @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
*
 */

并在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"
                            }
                        }
                    }
                }
            }
        },

希望这将有助于任何一个搜索如何使用多个例子来进行响应或请求。

Answer 2

谢谢@Fadi的指点。你的回答帮了我很大的忙，弄清楚了如何让这件事奏效。要想让它与zircote/swagger-php 3.2.3一起运行，我需要稍微修改一下：

     * @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"),
     *             },
     *         ),
     *     ),

我需要将example添加到示例定义中，以定义可以引用的键。我还必须在example中添加一个@OA\Schema键，不知道为什么或者做什么。但是没有它，我得到了User Warning: @OA\Schema() is missing key-field: "example"

由于我们的请求是JSON，所以在示例value中有一个复杂的结构。它可以工作，但是我不得不对数组使用{}，因为[]会导致错误Expected PlainValue, got '['。然后以数组的形式正确地输出事物。