Laravel - OpenAPI Generator 사용법 (OAS)

Laravel의 openapi:generate artisan 명령을 사용하면 OpenAPI를 위한 사양파일(OpenAPI Specification)을 생성할 수 있습니다.
생성된 문서는 다른 개발자 또는 자동화된 툴링을 위한 API의 구조와 동작을 설명하는 데 사용될 수 있습니다. (swagger, redoc, etc...)


다음은 Laravel에서 openapi:generate artisan 명령을 사용하는 방법입니다.

• composer를 이용하여 OpenAPI 패키지를 설치합니다. (vyuldashev 가 괜찮은듯..)

composer require vyuldashev/laravel-openapi

• config/app.php > provider에 서비스 패키지를 추가

'providers' => [
    // ...
    Vyuldashev\LaravelOpenApi\OpenApiServiceProvider::class,
];

• config 파일을 생성

php artisan vendor:publish --provider="Vyuldashev\LaravelOpenApi\OpenApiServiceProvider" --tag="openapi-config"

생성하면 config 파일이 생성됩니다.
여기서는 기본적인 설정을 해줍시다. (info와 servers 정도만 해주면 됩니다.)

 

• openapi:generate 명령어를 실행합니다.

php artisan openapi:generate

결과는 uri 기본 설정이 /openapi 이기 때문에 'localhost/openapi' 로 확인이 가능합니다.

반응형

 

 

• Api 정의

이제 openapi 로 표현할 사양을 정의 해주시면 됩니다.
자세한 문법은 vyuldashev 홈페이지 참고.

use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class testController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Response
     */
    #[OpenApi\Operation(tags: ['test'], method: 'GET')]
    public function index()
    {
        //
        return 'Hi Laravel';
    }
}

### use Vyuldashev\LaravelOpenApi\Attributes as OpenApi; - 패키지 사용.
### #[OpenApi\PathItem] - PATH 지정
### #[OpenApi\Operation(tags: ['test'], method: 'GET')] - Api 정의

또한 해당 결과 값을 flie_put_contents 로 파일로 생성할수도 있습니다.

패키지 controller에서 generate 전에 파일을 생성

 

• 생성된 JSON 파일.

---

Resources

https://vyuldashev.github.io/laravel-openapi/

Introduction | Laravel OpenAPI

https://redocly.com/

The Best API Documentation Tool

https://swagger.io/specification/

OpenAPI Specification - Version 3.0.3 | Swagger