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

Question

我正在尝试在文件中定义一些请求正文示例，并且 link 这个文件是实际请求，我看到我们可以使用 Swagger $ref 来做到这一点 Reusing Examples 但我可以找不到正确的 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 但 Example Value 在 ui

中仍然是空的

Answer 1

我找到了正确的 L5 语法来使用 refs 做多个例子：

所以首先我将示例定义为：

/**
 *      @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 我需要 fiddle 大约一点：

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

由于我们的请求是 JSON，我们在示例中有一个复杂的结构 value。它有效，但我必须对数组使用 {}，因为 [] 会导致错误 Expected PlainValue, got '['。然后事情以某种方式正确输出为数组。

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

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

laravel

swagger

swagger-php

swagger-ui