Swagger php разные версии определения

Question

Я устанавливаю Swagger для моего API, используя аннотации swagger-php. Что я не могу понять, так это как определить различные определения ресурса.

у меня есть User класс, который имеет идентификатор, адрес электронной почты, пароль и телефон.

Следующая операция получает соответствующие параметры

create: email, password, phone

update: email, password, phone, oldPassword

get Опрация вернется id, email, phone + некоторые связанные модели, которые создаются и обновляются через разные конечные точки.

Таким образом, каждый из них использует свое собственное определение User и я не уверен, как определить это аккуратно, не дублируя свойства в разных определениях (СУХОЙ).

Я думал о создании

BaseUser с email, phone,

затем NewUser что бы добавить password

затем UpdateUser добавление oldPassword

а также FullUser объединяя BaseUser со свойствами отношения только для чтения.

Но, черт возьми, это так сложно для такой тривиальной вещи, и весь этот эталонный ад затем будет отражен в swagger.json.

Есть ли решение для такой проблемы?

Answer 1

Вы можете использовать Swagger Definition с extends особенность.

1. Сделать BaseUser с электронной почтой и паролем

/**
 * Class BaseUser
 * @SWG\Definition(
 *     type="object",
 *     required={"email", "password"},
 * )
 */
class BaseUser
{
    /**
     * User's email address.
     *
     * @var string
     * @SWG\Property(example="[e-mail]")
     */
    public $email;

    /**
     * User's password.
     *
     * @var string
     * @SWG\Property(example="password")
     */
    public $password;
}

2. Создать определение UserCreate, расширяющее BaseUser

/**
 * Class UserCreate
 * @SWG\Definition(
 *     type="object",
 *     required={"phone_number"},
 * )
 */
class UserCreate extends BaseUser
{
    /**
     * User's phone number.
     *
     * @var integer
     * @SWG\Property(example=9876543210)
     */
    public $phone_number;
}

3. Создать определение UserUpdate, расширяющее UserCreate

/**
 * Class UserUpdate
 * @SWG\Definition(
 *     type="object",
 *     required={"old_password"},
 * )
 */
class UserUpdate extends UserCreate
{
    /**
     * User's old or existing password.
     *
     * @var string
     * @SWG\Property(example="old-password")
     */
    public $old_password;
}

Вы можете расширить свои определения на любом уровне, но дело в том, что ваши обязательные атрибуты должны быть перечислены в вашем последнем определении.

Вывод будет таким, как показано.