避免 NelmioApiDoc 响应中的数据冗余：自定义模式有什么妙招？

php

2024-03-11 04:44:05

避免 NelmioApiDoc 响应中的数据冗余：使用自定义模式

简介

在使用 NelmioApiDoc 生成 OpenAPI 文档时，你可能会遇到一个问题：当在多个响应中重复使用相同的响应结构时，schema 会被冗余数据污染。这会让输出难以阅读和理解。

解决方案：自定义模式

为了解决这个问题，我们可以为共享的响应结构创建一个自定义模式。这将允许我们在不同的响应中重用模式，而不会污染 schema 视图。

步骤

创建自定义模式： 在 config/swagger.yaml 文件中定义一个模式：

SuccessResponse:
    description: OK
    properties:
        status: { type: string, example: OK }
        code: { type: integer, example: 20000 }
        data: { type: array }

使用自定义模式： 在响应中引用模式：

 * @OA\Response(
 *     response=200,
 *     description="Success",
 *     @OA\JsonContent(
 *         allOf={
 *             @OA\Schema(ref="#/components/schemas/SuccessResponse"),
 *             @OA\Schema(type="object",
 *               @OA\Property(
 *                 property="data",
 *                 ref=@Model(type=OutputDto::class)
 *               )
 *             )
 *         }
 *     )
 * )