Laravel 12 Swagger

✅ 1. 패키지 설치

composer require "darkaonline/l5-swagger"

주의: L5-Swagger는 Laravel 5~12까지 호환됩니다.

---

✅ 2. 퍼블리시 설정 파일 및 뷰

php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"

이 명령은 다음 파일을 생성합니다:

• config/l5-swagger.php
• resources/views/vendor/l5-swagger

---

✅ 3. 설정 파일 수정 (선택)

config/l5-swagger.php에서 필요에 따라 설정을 조정합니다. 예를 들어 API 문서 경로, 기본 네임스페이스 등을 변경할 수 있습니다.

예:

'paths' => [
    'docs' => storage_path('api-docs'),
    'annotations' => base_path('app'),
],

---

✅ 4. 라우트로 접속하기 위한 설정

기본적으로 아래 주소로 Swagger UI에 접속할 수 있습니다:

http://your-app-url/api/documentation

 

라우트를 바꾸고 싶으면 config/l5-swagger.php의 routes 설정을 수정하세요:

'routes' => [
    'api' => 'api/documentation',
],

---

✅ 5. 주석으로 API 문서 작성

Swagger는 주석 기반으로 API 문서를 생성합니다. 예:

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="Get list of users",
 *     @OA\Response(
 *         response=200,
 *         description="Successful operation"
 *     )
 * )
 */
public function index()
{
    return User::all();
}

---

✅ 6. 문서 생성

php artisan l5-swagger:generate

 

이 명령어는 storage/api-docs에 Swagger JSON 파일을 생성합니다.

---

✅ 7. Swagger UI 접속

브라우저에서 아래 URL 접속:

http://your-app-url/api/documentation

---

🛠️ 참고 사항

• swagger-php는 PHP 8 이상에서 작동하며, PHPDoc 주석을 인식합니다.
• Swagger 어노테이션을 쉽게 사용하려면 Swagger-PHP 문서를 참고하세요.
• Laravel 12에서 route caching이 Swagger UI에 영향을 줄 수 있으니 개발 중에는 php artisan route:clear를 자주 해주세요.