Laravel eloquent 模型與 swagger openApi 註解問題

Question

因此，在我的使用者模型中，我有一個函數 fullname 傳回使用者的全名：

/**
 * @return Attribute
 */
public function fullname(): Attribute
{
    return new Attribute(
        get: fn () => trim($this->firstname . ' ' . $this->lastname),
    );
}

它按預期工作，現在我想在我的模型上添加 OpenAPI 註釋： 我是這樣做的：

class User extends Authenticatable
{
    ...
       
    protected $appends = [
        'fullname'
    ];

    #[OAProperty(type: "string", example: "Jhon")] 
    private $firstname; 

    #[OAProperty(type: "string", example: "Doe")] 
    private $lastname;
    
    /**
     * @return Attribute
     */
    public function fullname(): Attribute
    {
        return new Attribute(
            get: fn () => trim($this->firstname . ' ' . $this->lastname),
        );
    }
}

此時該功能不再如預期運作：

$this->firstname and $this->lastname

不再傳回空值。

問題：我想保留註釋，但也要讓函數工作。

注意：如果您透過 eloquent ex 存取您的使用者。 （ User::all()->first(); ）我們得到了名字和姓氏，但沒有得到全名，感謝您的幫助

Answer 1

https://github.com/DarkaOnLine/L5-Swagger/issues/157

#根據這個問題： 在模型上定義屬性會產生很多 eloquent 的問題

我找到了 3 種方法來解決這個問題：

選項 1：您需要進行的重構量最少

#保留註解並刪除屬性定義，例如： 這：

#[OA\Property(type: "string", example: "Jhon")] 
private $firstname; 

#[OA\Property(type: "string", example: "Doe")] 
private $lastname;

will become 這：

#[OA\Property(property: "firstname", type: "string", example: "Jhon")] 
#[OA\Property(property: "lastname",type: "string", example: "Doe")]

注意：屬性或註解必須位於變數或函數之上，否則會產生錯誤。

選項 2：更乾淨，但增加了更多工作

將您的開放 API 聲明放在其他地方。例如：

• 回覆資源：https://github.com/DarkaOnLine/ L5-Swagger/issues/157#issuecomment-406204764
• #建立一個新目錄（虛擬）並將所有 OpenAPI 註解放在那裡：https://github.com/DarkaOnLine/L5-Swagger/issues/157#issuecomment-655865772

選項 3： 這就是我使用的

將您的屬性加入到架構聲明中 範例：

#[OA\Schema(schema: "IUser", properties: [
    new OA\Property(property: "firstname", type: "string", example: "Jhon"),
    new OA\Property(property: "lastname",type: "string", example: "Doe")
])]