l5-swagger Response에 Schema + Property 추가하기

이슈

`l5-swagger` 사용시 모델에 정의된 Schema에 Resource에 맞는 Property를 추가하는데 이슈가 있었다.
https://github.com/DarkaOnLine/L5-Swagger?tab=readme-ov-file

GitHub - DarkaOnLine/L5-Swagger: OpenApi or Swagger integration to Laravel

Github에도 자세한 메뉴얼이 없다보니 사용하는데 에로사항이 조금 있었는데, 우연히 검색하는 과정에서 발견하게 되어 작성해 본다.

구글에서 검색시 laravel 사용자는 swagger 사용시 l5-swagger를 많이 사용하는 듯한데 도움이 되지 않을까?

 

해결 방안

// AwesomeModel.php
<?php
#[OA\Schema(
    type : 'object',
    schema: "AwesomeModel",
    properties: [
        new OA\Property(property: 'id', type: 'integer', description: "id"),
        new OA\Property(property: 'name', type: 'string', description: "name"),
        new OA\Property(property: 'status', type: 'string', description: "상태"),
    ],
)]
class AwesomeModel {}

// AwesomeController.php
<?php

#[OA\Get(
   ...
)]
#[OA\Response(
    response:200,
    ref:"#/components/responses/AwesomeResource",
)]
#[OA\Response(response:400, ref:"#/components/responses/BadRequest")]
class AwesomeController {}

 

// AwesomeResource.php
<?php

#[OA\Response(
    description:"Success",
    response: "AwesomeResource",
    content: new OA\JsonContent(
        properties: [
            new OA\Property(
                property: 'data',
                type: "array",
                items: new OA\Items(
                    allOf:[
                        new OA\Schema(ref:"#/components/schemas/AwesomeModel"),
                        new OA\Schema(properties: [
                            new OA\Property(property:'created_at', type: 'string', format:"date", description: "생성일"),
                        ]),
                    ],
                ),
            ),
        ],
    )
)]
class AwesomeResource extends JsonResource
{
    public function toArray(Request $request)
    {
        $response = parent::toArray($request);
        return [
            ...$response,
            'created_at' => $this->anotherModel->createdAt,
        ];
    }
}

 

요점은 `allOf`를 통해 여러개 스키마를 묶어 줄 수 있다.

allOf:[
    new OA\Schema(),
    new OA\Schema(),
],

 

참고

https://stackoverflow.com/questions/64387159/l5-swagger-how-to-add-examples-for-request-body-or-response-body

L5 Swagger - how to add examples for request body or response body