가이드
명세
OpenAPI 명세를 자동으로 생성하는 방법을 알아봅니다.
내장된 OpenAPI 명세 생성 기능을 사용하면 코드 변경 없이 명세를 생성할 수 있습니다.
php artisan orion:specs
이 명령을 실행하면 storage/app/specs 디렉터리 안에 specs.json 파일이 생성됩니다.
커스터마이징
Info 및 Servers
명세의 info와 servers 필드는 orion.php 설정 파일에서 채워집니다.
'specs' => [
'info' => [
'title' => env('APP_NAME'),
'description' => null,
'terms_of_service' => null,
'contact' => [
'name' => null,
'url' => null,
'email' => null,
],
'license' => [
'name' => null,
'url' => null,
],
'version' => '1.0.0',
],
'servers' => [
['url' => env('APP_URL').'/api', 'description' => 'Default Environment'],
],
],
아직 설정 파일을 퍼블리시하지 않았다면 다음 명령을 실행하여 퍼블리시할 수 있습니다.
php artisan vendor:publish --tag=orion-config
파일 경로
파일을 다른 경로(예: storage/app/specs/example.yaml)에 저장하려면 --path 옵션을 제공하여 간단히 커스터마이징할 수 있습니다. 지정하는 경로는 상대 경로라는 점에 유의하세요.
php artisan orion:specs --path="specs/example.yaml"
파일 형식
기본적으로 명세 파일은 .json 형식으로 저장됩니다. 하지만 --format 옵션을 제공하면 .yaml 형식으로도 저장할 수 있습니다.
php artisan orion:specs --format="yaml"
기존 명세
이미 커스텀 엔드포인트와 해당 OpenAPI 명세가 있다면, 기존 명세 파일을 storage/app 디렉터리 안의 원하는 위치에 두고 명령에 --path 옵션을 제공하면 됩니다. 그러면 표준 엔드포인트에 대한 명세를 생성한 뒤 기존(커스텀) 명세와 병합합니다. 지정하는 경로는 상대 경로라는 점에 유의하세요.
php artisan orion:specs --path="specs/existing-specs.json"
현재 생성기는 표준(Orion이 제공하는) 엔드포인트만 지원합니다. 직접 만든 커스텀 엔드포인트에 대한 명세는 생성되지 않습니다.
다만 다음 릴리스에서 이를 지원할 계획이 있습니다.