PHP Swagger OpenApi泛型类型

djmepvbi 于 2023-10-18 发布在 PHP

关注(0)|答案(2)|浏览(126)

我使用zircote/swagger-php作为注解来为我的php WebApi生成swagger。
我有我的通用模型HttpResponse，它有2个常见的属性（messages和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);
    }
}

swagger

来源：https://stackoverflow.com/questions/71901795/php-swagger-openapi-generic-type

2条答案

按热度按时间

dnph8jn41#

你应该使用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{}

赞(0）回复(0）举报 2023-10-18

wxclj1h52#

也许你应该使用一个如这里所描述的插件：https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/

赞(0）回复(0）举报 2023-10-18