PHP Swagger OpenAPI通用类型

Question

我正在使用 Zircote/Swagger-php 用于注释以生成我的php webapi的Swagger。
我有我的通用模型 httpresponse ，它具有2个常见属性（消息和 statuscode ），但是 data 是通用和每个端点都有不同的类型。

我正在尝试通过 Zircote/Swagger-PHP 对其进行报道，并为此 Data 属性使用不同的模型。谁能告诉我如何做到这一点？

现在，我正在尝试以下类似的事情，但是它首先给了我每个请求的 anyof ，而是让我具体说明我想要哪个请求。

/**
 * @OA\Schema()
 */
class HttpResponse
{
    /**
     * @OA\Property(anyOf={
     *          @OA\Schema(ref="#/components/schemas/HolidayRequestSpecificInput"),
     *          @OA\Schema(ref="#/components/schemas/AvailableHolidayDatesApiModel")
     *       })
     */
    public $data;
    /**
     * @OA\Property(type="array", @OA\Items(ref="#/components/schemas/Message"))
     */
    public $messages;
    /**
     * @OA\Property(ref="#/components/schemas/HttpResponseType")
     */
    public $statusCode;

    public function __construct($statusCode = HttpResponseType::Ok, $data = null)
    {
        $this->data = $data;
        $this->messages = [];
        $this->statusCode = $statusCode;
    }

    public function addMessages($messages)
    {
        foreach ($messages as $msg)
            array_push($this->messages, $msg);
    }
}

Answer 1

可能是您应该使用 Oneof 而不是 anyof 。

但是，现在设置了事物，现在每个端点都将返回 httpresponse ，并选择不理想的数据结构。

更好的是，恕我直言，是让每个端点准确定义其返回的数据（除非我误解了您的代码）。

在这种情况下，我建议您将响应架构分为基础，并明确 @OA \ response 每个端点的定义。

缺点可能是注释不能准确反映您的代码。但是，规格将更明确地反映出端点返回的数据结构。

/**
 * @OA\Schema()
 */
class BaseResponse
{
    /**
     * @OA\Property(type="array", @OA\Items(ref="#/components/schemas/Message"))
     */
    public $messages;

    /**
     * @OA\Property(ref="#/components/schemas/HttpResponseType")
     */
    public $statusCode;
}

/**
 * @OA\Schema()
 */
class HolidayRequestSpecificInput{
    /**
     * @OA\Property()
     */
    public $location;

}

/**
 * @OA\Get(path="/holiday",
 *     @OA\Response(
 *         response="200",
 *         description="OK",
 *         @OA\JsonContent(
 *             allOf={
 *                 @OA\Schema(ref="#/components/schemas/BaseResponse"),
 *                 @OA\Schema(
 *                     @OA\Property(property="data", ref="#/components/schemas/HolidayRequestSpecificInput")
 *                 )
 *             }
 *         )
 *     )
 * )
 */
class Controller{}

Answer 2

也许您应该使用此处描述的歧视器：